Skip to main content
Previous section   

Native API for .NET Quick Reference

This is a quick reference for the InterSystems IRIS Native API for .NET, providing information on the following classes in InterSystems.Data.IRISClient.ADO:
  • Class IRIS provides the main functionality of the Native API.
  • Class IRISIterator provides methods to navigate a global array.
  • Class IRISObject provides methods to work with Object Gateway reverse proxy objects.
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, see the online class documentation.
All methods listed in the following sections will throw an exception on encountering any kind of error. Throughout the API, the subscript argument
Object[] args
is defined as
params object[]
.

Class IRIS

Class IRIS is a member of InterSystems.Data.IRISClient.ADO.
Instances of IRIS are created by calling static method IRIS.CreateIRIS().

Method Details

ClassMethodBool()
ADO.IRIS.ClassMethodBool() calls an ObjectScript class method, passing zero or more arguments and returning an instance of bool?. See “Calling ObjectScript Methods and Functions” for details and examples.
bool? ClassMethodBool(string className, string methodName, params object[] 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 arguments of supported types.
ClassMethodBytes()
ADO.IRIS.ClassMethodBytes() calls an ObjectScript class method, passing zero or more arguments and returning an instance of byte[]. See “Calling ObjectScript Methods and Functions” for details and examples.
byte[] ClassMethodBytes(string className, string methodName, params object[] 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 arguments of supported types.
ClassMethodDouble()
ADO.IRIS.ClassMethodDouble() calls an ObjectScript class method, passing zero or more arguments and returning an instance of double?. See “Calling ObjectScript Methods and Functions” for details and examples.
double? ClassMethodDouble(string className, string methodName, params object[] 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 arguments of supported types.
ClassMethodLong()
ADO.IRIS.ClassMethodLong() calls an ObjectScript class method, passing zero or more arguments and returning an instance of long?. See “Calling ObjectScript Methods and Functions” for details and examples.
long? ClassMethodLong(string className, string methodName, params object[] 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 arguments of supported types.
ClassMethodObject()
ADO.IRIS.ClassMethodObject() calls an ObjectScript class method, passing zero or more arguments and returning an instance of object. If the returned object is a valid OREF (for example, if %New() was called), ClassMethodObject() will generate and return a reverse proxy object (an instance of IRISObject) for the referenced object. See “Using .NET Reverse Proxy Objects” for details and examples.
Object ClassMethodObject(string className, string methodName, params object[] 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 arguments of supported types.
ClassMethodString()
ADO.IRIS.ClassMethodString() calls an ObjectScript class method, passing zero or more arguments and returning an instance of string. See “Calling ObjectScript Methods and Functions” for details and examples.
string ClassMethodString(string className, string methodName, params object[] 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 arguments of supported types.
ClassMethodVoid()
ADO.IRIS.ClassMethodVoid() calls an ObjectScript class method with no return value, passing zero or more arguments. See “Calling ObjectScript Methods and Functions” for details and examples.
void ClassMethodVoid(string className, string methodName, params object[] 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 arguments of supported types.
Close()
ADO.IRIS.Close() closes the IRIS object.
void Close()
CreateIRIS()
ADO.IRIS.CreateIRIS() returns an instance of ADO.IRIS that uses the specified IRISConnection.
static IRIS CreateIRIS(IRISADOConnection conn)
parameters:
See “Introduction to Global Arrays” for more information and examples.
FunctionBool()
ADO.IRIS.FunctionBool() calls an ObjectScript function, passing zero or more arguments and returning an instance of bool?. See “Calling ObjectScript Methods and Functions” for details and examples.
bool? FunctionBool(string functionName, string routineName, params object[] args)
parameters:
  • functionName
    — name of the function to call.
  • routineName
    — name of the routine containing the function.
  • args
    — zero or more arguments of supported types.
FunctionBytes()
ADO.IRIS.FunctionBytes() calls an ObjectScript function, passing zero or more arguments and returning an instance of byte[]. See “Calling ObjectScript Methods and Functions” for details and examples.
byte[] FunctionBytes(string functionName, string routineName, params object[] args)
parameters:
  • functionName
    — name of the function to call.
  • routineName
    — name of the routine containing the function.
  • args
    — zero or more arguments of supported types.
FunctionDouble()
ADO.IRIS.FunctionDouble() calls an ObjectScript function, passing zero or more arguments and returning an instance of double?. See “Calling ObjectScript Methods and Functions” for details and examples.
double? FunctionDouble(string functionName, string routineName, params object[] args)
parameters:
  • functionName
    — name of the function to call.
  • routineName
    — name of the routine containing the function.
  • args
    — zero or more arguments of supported types.
FunctionInt()
ADO.IRIS.FunctionInt() calls an ObjectScript function, passing zero or more arguments and returning an instance of long?. See “Calling ObjectScript Methods and Functions” for details and examples.
long? FunctionInt(string functionName, string routineName, params object[] args)
parameters:
  • functionName
    — name of the function to call.
  • routineName
    — name of the routine containing the function.
  • args
    — zero or more arguments of supported types.
FunctionObject()
ADO.IRIS.FunctionObject() calls an ObjectScript function, passing zero or more arguments and returning an instance of object. If the returned object is a valid OREF, FunctionObject() will generate and return a reverse proxy object (an instance of IRISObject) for the referenced object. See “Using .NET Reverse Proxy Objects” for details and examples.
Object FunctionObject(string functionName, string routineName, params object[] args)
parameters:
  • functionName
    — name of the function to call.
  • routineName
    — name of the routine containing the function.
  • args
    — zero or more arguments of supported types.
FunctionString()
ADO.IRIS.FunctionString() calls an ObjectScript function, passing zero or more arguments and returning an instance of string. See “Calling ObjectScript Methods and Functions” for details and examples.
string FunctionString(string functionName, string routineName, params object[] args)
parameters:
  • functionName
    — name of the function to call.
  • routineName
    — name of the routine containing the function.
  • args
    — zero or more arguments of supported types.
GetAPIVersion() [static]
ADO.IRIS.GetAPIVersion() returns the IRIS Native API version string.
static String GetAPIVersion()
GetBool()
ADO.IRIS.GetBool() gets the value of the global as a bool? (or
null
if node does not exist). Returns
false
if node value is empty string.
bool? GetBool(string globalName, params object[] subscripts)
parameters:
  • globalName
    — global name.
  • subscripts
    — zero or more subscripts specifying the target node.
GetBytes()
ADO.IRIS.GetBytes() gets the value of the global as a byte[] (or
null
if node does not exist).
byte[] GetBytes(string globalName, params object[] subscripts)
parameters:
  • globalName
    — global name.
  • subscripts
    — zero or more subscripts specifying the target node.
GetDateTime()
ADO.IRIS.GetDateTime() gets the value of the global as a DateTime? (or
null
if node does not exist).
DateTime? GetDateTime(string globalName, params object[] subscripts)
parameters:
  • globalName
    — global name.
  • subscripts
    — zero or more subscripts specifying the target node.
GetDouble()
ADO.IRIS.GetDouble() gets the value of the global as a double? (or
null
if node does not exist). Returns
0.0
if node value is empty string.
Double? GetDouble(string globalName, params object[] subscripts)
parameters:
  • globalName
    — global name.
  • subscripts
    — zero or more subscripts specifying the target node.
GetInt16()
ADO.IRIS.GetInt16() gets the value of the global as an Int16? (or
null
if node does not exist). Returns 0 if node value is empty string.
Int16? GetInt16(string globalName, params object[] subscripts)
parameters:
  • globalName
    — global name.
  • subscripts
    — zero or more subscripts specifying the target node.
GetInt32()
ADO.IRIS.GetInt32() gets the value of the global as an Int32? (or
null
if node does not exist). Returns 0 if node value is empty string.
Int32? GetInt32(string globalName, params object[] subscripts)
parameters:
  • globalName
    — global name.
  • subscripts
    — zero or more subscripts specifying the target node.
GetInt64()
ADO.IRIS.GetInt64() gets the value of the global as an Int64? (or
null
if node does not exist). Returns 0 if node value is empty string.
Int64? GetInt64(string globalName, params object[] subscripts)
parameters:
  • globalName
    — global name.
  • subscripts
    — zero or more subscripts specifying the target node.
GetIRISIterator()
ADO.IRIS.GetIRISIterator() returns an IRISIterator object (see “Class IRISIterator”) for the specified node with search direction set to
FORWARD
. See “Iterating Over a Set of Child Nodes” for more information and examples.
IRISIterator GetIRISIterator(string globalName, params object[] subscripts)
parameters:
  • globalName
    — global name.
  • subscripts
    — zero or more subscripts specifying the target node.
GetIRISReverseIterator()
ADO.IRIS.GetIRISReverseIterator() returns an IRISIterator object (see “Class IRISIterator”) for the specified node with search direction set to
BACKWARD
. See “Iterating Over a Set of Child Nodes” for more information and examples.
IRISIterator GetIRISReverseIterator(string globalName, params object[] subscripts)
parameters:
  • globalName
    — global name.
  • subscripts
    — zero or more subscripts specifying the target node.
GetObject()
ADO.IRIS.GetObject() gets the value of the global as an Object (or
null
if node does not exist). See “Using .NET Reverse Proxy Objects” for details and examples.
object GetObject(string globalName, params object[] subscripts)
parameters:
  • globalName
    — global name.
  • subscripts
    — zero or more subscripts specifying the target node.
GetServerVersion()
ADO.IRIS.GetServerVersion() returns the server version string for the current connection. This is equivalent to calling
$system.Version.GetVersion()
in ObjectScript.
String GetServerVersion()
GetSingle()
ADO.IRIS.GetSingle() gets the value of the global as a Single? (Nullable<float>) or
null
if node does not exist. Returns
0.0
if node value is an empty string.
Single? GetSingle(string globalName, params object[] subscripts)
parameters:
  • globalName
    — global name.
  • subscripts
    — zero or more subscripts specifying the target node.
GetString()
ADO.IRIS.GetString() gets the value of the global as a string (or
null
if node does not exist).
Empty string and null values require some translation. An empty string
""
in .NET is translated to the null string character
$CHAR(0)
in ObjectScript. A null in .NET is translated to the empty string in ObjectScript. This translation is consistent with the way .NET handles these values.
string GetString(string globalName, params object[] subscripts)
parameters:
  • globalName
    — global name.
  • subscripts
    — zero or more subscripts specifying the target node.
GetTLevel()
ADO.IRIS.GetTLevel() gets the level of the current nested transaction. Returns 1 if there is only a single transaction open. Returns 0 if there are no transactions open. This is equivalent to fetching the value of the $TLEVEL special variable. See “Transactions and Locking” for more information and examples.
int? GetTLevel()
Increment()
ADO.IRIS.Increment() increments the specified global with the passed value. If there is no node at the specified address, a new node is created with
value
as the value. A null value is interpreted as 0. Returns the new value of the global node. See “Creating, Updating, and Deleting Nodes” for more information and examples.
long Increment(long? value, string globalName, params object[] subscripts)
parameters:
  • value
    long value to which to set this node (
    null
    value sets global to
    0
    ).
  • globalName
    — global name.
  • subscripts
    — zero or more subscripts specifying the target node.
IsDefined()
ADO.IRIS.IsDefined() returns a value indicating whether the specified node exists and if it contains a value. See “Testing for Child Nodes and Node Values” for more information and examples.
int IsDefined(string globalName, params object[] subscripts))
parameters:
  • globalName
    — global name.
  • subscripts
    — zero or more subscripts specifying the target node.
return values:
  • 0
    — the specified node does not exist
  • 1
    — the node exists and has a value
  • 10
    — the node is valueless but has subnodes
  • 11
    — the node has both a value and subnodes
Kill()
ADO.IRIS.Kill() deletes the global node including any descendants. See “Creating, Updating, and Deleting Nodes” for more information and examples.
void Kill(string globalName, params object[] subscripts)
parameters:
  • globalName
    — global name.
  • subscripts
    — zero or more subscripts specifying the target node.
Lock()
ADO.IRIS.Lock() locks the global, returns true on success. Note that this method performs an incremental Lock and not the implicit Unlock before Lock feature that is also offered in ObjectScript. See “Transactions and Locking” for more information and examples.
bool Lock(string lockMode, int timeout, string globalName, params object[] subscripts)
parameters:
  • lockMode
    — Character
    S
    for shared Lock,
    E
    for escalating Lock, or
    SE
    for both. Default is empty string (exclusive and non-escalating).
  • timeout
    — amount to wait to acquire the Lock in seconds.
  • globalName
    — global name.
  • subscripts
    — zero or more subscripts specifying the target node.
Procedure()
ADO.IRIS.Procedure() calls a procedure, passing zero or more arguments. Does not return a value. See “Calling ObjectScript Methods and Functions” for more information and examples.
void Procedure(string procedureName, string routineName, params object[] args)
parameters:
  • procedureName
    — name of the procedure to call.
  • routineName
    — name of the routine containing the procedure.
  • args
    — zero or more arguments of supported types.
ReleaseAllLocks()
ADO.IRIS.ReleaseAllLocks() releases all locks associated with the session. See “Transactions and Locking” for more information and examples.
void ReleaseAllLocks()
Set()
ADO.IRIS.Set() sets the current node to a value of a supported datatype (or
""
if the value is
null
). If there is no node at the specified node address, a new node will be created with the specified value. See “Creating, Updating, and Deleting Nodes” for more information.
void Set(bool? value, string globalName, params object[] subscripts)
void Set(byte[] value, string globalName, params object[] subscripts)
void Set(DateTime? value, string globalName, params object[] subscripts)
void Set(Double? value, string globalName, params object[] subscripts)
void Set(Int16? value, string globalName, params object[] subscripts)
void Set(Int32? value, string globalName, params object[] subscripts)
void Set(Int64? value, string globalName, params object[] subscripts)
void Set(IRISList value, String globalName, params object[] subscripts)
void Set(object value, string globalName, params object[] subscripts)
void Set(Single? value, string globalName, params object[] subscripts)
void Set(string value, string globalName, params object[] subscripts)
void Set(System.IO.MemoryStream value, string globalName, params object[] subscripts)
parameters:
  • value
    — value of a supported datatype (
    null
    value sets global to
    ""
    ).
  • globalName
    — global name.
  • subscripts
    — zero or more subscripts specifying the target node.
Notes on specific datatypes
The following datatypes have some extra features:
  • string — empty string and null values require some translation. An empty string
    ""
    in .NET is translated to the null string character
    $CHAR(0)
    in ObjectScript. A null in .NET is translated to the empty string in ObjectScript. This translation is consistent with the way .NET handles these values.
TCommit()
ADO.IRIS.TCommit() commits the current transaction. See “Transactions and Locking” for more information and examples.
void TCommit()
TRollback()
ADO.IRIS.TRollback() rolls back all open transactions in the session. See “Transactions and Locking” for more information and examples.
void TRollback()
TRollbackOne()
ADO.IRIS.TRollbackOne() rolls back the current level transaction only. If this is a nested transaction, any higher-level transactions will not be rolled back. See “Transactions and Locking” for more information and examples.
void TRollbackOne()
TStart()
ADO.IRIS.TStart() starts/opens a transaction. See “Transactions and Locking” for more information and examples.
void TStart()
Unlock()
ADO.IRIS.Unlock() unlocks the global. This method performs an incremental Unlock, not the implicit Unlock-before-Lock feature that is also offered in ObjectScript. See “Transactions and Locking” for more information and examples.
void Unlock(string lockMode, string globalName, params object[] subscripts)
parameters:
  • lockMode
    — Character
    S
    for shared Lock,
    E
    for escalating Lock, or
    SE
    for both. Default is empty string (exclusive and non-escalating).
  • globalName
    — global name.
  • subscripts
    — zero or more subscripts specifying the target node.

Class IRISIterator

Instances of IRISIterator are created by calling one of the following IRIS methods:
See “Iterating Over a Set of Child Nodes” for more information and examples.
This class implements required IEnumerator method System.Collections.IEnumerator.GetEnumerator(), which is invoked when the iterator is used in a
foreach
loop.
All methods listed in the following sections will throw an exception on encountering any kind of error.

Method and Property Details

Property Current
ADO.IRISIterator.Current gets the value of the node at the current iterator position. In a
foreach
loop, this value is also assigned to the current loop variable. See “Iteration in Conditional Loops” for more information and examples.
object Current get;
Property CurrentSubscript
ADO.IRISIterator.CurrentSubscript gets the lowest level subscript for the node at the current iterator position. For example, if the iterator points to node ^myGlobal(23,"somenode"), the returned value will be
"somenode"
. See “Iteration in Conditional Loops” for more information and examples.
object CurrentSubscript get;
MoveNext()
ADO.IRISIterator.MoveNext() implements System.Collections.IEnumerator. It returns
true
if the next value was retrieved,
false
if there are no more values. See “Iteration in Conditional Loops” for more information and examples.
bool MoveNext()
Reset()
ADO.IRISIterator.Reset() can be called after completing a
foreach
loop to reset the iterator to its starting position, allowing it to be used again. See “Iteration in Conditional Loops” for more information and examples.
void Reset()
StartFrom()
ADO.IRISIterator.StartFrom() sets the iterator's starting position to the specified subscript. The subscript is an arbitrary starting point, and does not have to specify an existing node. See “Iterating Over a Set of Child Nodes” for more information and examples.
void  StartFrom(Object subscript)

Class IRISObject

Instances of IRISObject are created by calling one of the following IRIS methods:
If the called method or function returns an object that is a valid OREF, a reverse proxy object (an instance of IRISObject) for the referenced object will be generated and returned. For example, ClassMethodObject() will return a proxy object for an object created by %New().
See “Using .NET Reverse Proxy Objects” for details and examples.

IRISObject Method Details

Dispose()
ADO.IRISObject.Dispose() releases this instance of IRISObject.
void Dispose()
Get()
ADO.IRISObject.Get() returns a property of the object as object.
object Get(string propertyName)
parameters:
  • propertyName
    — name of the property to be returned.
Invoke()
ADO.IRISObject.Invoke() invokes an instance method of the object, returning value as object.
object Invoke(string methodName, params object[] args)
parameters:
  • methodName
    — name of the instance method to be called.
  • args
    — zero or more arguments of supported types.
InvokeVoid()
ADO.IRISObject.InvokeVoid() invokes an instance method of the object, but does not return a value.
void InvokeVoid(string methodName, params object[] args)
parameters:
  • methodName
    — name of the instance method to be called.
  • args
    — zero or more arguments of supported types.
Set()
ADO.IRISObject.Set() sets a property of the object.
void Set(string propertyName, Object value)
parameters:
  • propertyName
    — name of the property to which value will be assigned.
  • value
    — property value to assign.
Previous section