Using .NET with Caché eXTreme
Quick Reference for eXTreme Classes
[Home] [Back] 
InterSystems: The power behind what matters   
Class Reference   
Search:    

This chapter is a quick reference for the classes that are most important to an understanding of the following Caché eXTreme APIs:

Note:
This is not the definitive reference for these APIs. For the most complete and up-to-date information, see the help file, located in <install-dir>/dev/dotnet/help/CacheExtreme.chm.
XEP Quick Reference
This section is a reference for the XEP API (eXTreme Event Persistence — namespace InterSystems.XEP). See Using eXTreme Event Persistence for a details on how to use the API. It contains the following classes and interfaces:
List of XEP Methods
The following classes and methods of the XEP API are described in this reference:
PersisterFactory
EventPersister
Event
EventQuery<>
InterfaceResolver
Class PersisterFactory
Class InterSystems.XEP.PersisterFactory creates a new EventPersister object.
PersisterFactory() Constructor
Creates a new instance of PersisterFactory.
PersisterFactory()
CreatePersister()
PersisterFactory.CreatePersister() returns an instance of EventPersister.
static EventPersister CreatePersister()
see also:
Creating and Connecting an EventPersister
Class EventPersister
Class InterSystems.XEP.EventPersister is the main entry point for the XEP module. It provides methods that can be used to set XEP options up, establish an XEP connection, import schema, and produce XEP Event objects. It also provides methods to control transactions and perform other tasks.
CallBytesClassMethod()
EventPersister.CallBytesClassMethod() — calls a ObjectScript class method and returns an Object that may be of type int, long, double, or byte[].
This method is identical to CallClassMethod() except that it returns string values as instances of byte[] rather than String.
Object CallBytesClassMethod(string className, string methodName, params Object[] args)
parameters:
CallBytesFunction()
EventPersister.CallBytesFunction() calls a ObjectScript function (see User-defined Code in Using Caché ObjectScript) and returns an Object that may be of type int, long, double, or byte[].
This method is identical to CallFunction() except that it returns string values as instances of byte[] rather than String.
Object CallBytesFunction(string functionName, string routineName, params Object[] args)
parameters:
CallClassMethod()
EventPersister.CallClassMethod() — calls a ObjectScript class method and returns an Object that may be of type int, long, double, or String. Use CallVoidClassMethod() to call a method that doesn’t return a value, CallBytesClassMethod() to return string values as byte[], or CallListClassMethod() to return string values as ValueList.
Object CallClassMethod(string className, string methodName, params Object[] args)
parameters:
CallFunction()
EventPersister.CallFunction() — calls a ObjectScript function (see User-defined Code in Using Caché ObjectScript) and returns an Object that may be of type int, long, double, or String. Use CallBytesFunction() to return string values as byte[], or CallListFunction() to return string values as ValueList.
Object CallFunction(string functionName, string routineName, params Object[] args)
parameters:
CallListClassMethod()
EventPersister.CallListClassMethod() — calls a ObjectScript class method and returns an Object that may be of type int, long, double, or ValueList.
This method is identical to CallClassMethod() except that it returns string values as instances of ValueList rather than String.
Object CallListClassMethod(string className, string methodName, params Object[] args)
Throws an exception if the return value is a string but is not in valid ValueList format.
parameters:
CallListFunction()
EventPersister.CallListFunction() calls a ObjectScript function (see User-defined Code in Using Caché ObjectScript) and returns an Object that may be of type int, long, double, or ValueList.
This method is identical to CallFunction() except that it returns string values as instances of ValueList rather than String.
Object CallListFunction(string functionName, string routineName, params Object[] args)
Throws an exception if the return value is a string but is not in valid ValueList format.
parameters:
CallProcedure()
EventPersister.CallProcedure() calls a ObjectScript procedure (see User-defined Code in Using Caché ObjectScript).
void CallProcedure(string procedureName, string routineName, params Object[] args)
parameters:
CallVoidClassMethod()
EventPersister.CallVoidClassMethod() — calls a ObjectScript class method with no return value, passing 0 or more arguments. This method may be used to call any Caché class method (regardless of whether it normally returns a value) when the caller does not need the return value. Use CallClassMethod() to call a method that returns a value.
void CallVoidClassMethod(string className, string methodName, params Object[] args)
parameters:
Close()
EventPersister.Close() releases all resources held by this instance.
void Close()
It is important to always call Close() on an instance of EventPersister before it goes out of scope. Failing to close it can cause serious memory leaks because .NET garbage collection cannot release resources allocated by the underlying native code.
Commit()
EventPersister.Commit() commits one level of transaction
void Commit()
Connect()
EventPersister.Connect() connects to Caché using either an eXTreme connection or a TCP/IP connection, depending on the arguments specified. If only namespace, username, and password arguments are specified, an in-process eXTreme connection is established. If host and port are also specified, a TCP/IP connection is established.
void Connect(string nmspace, string username, string password)
void Connect(string host, int port, string nmspace, string username, string password)
parameters:
see also:
Creating and Connecting an EventPersister
DeleteClass()
EventPersister.DeleteClass() deletes a Caché class definition. It does not delete objects associated with the extent (since objects can belong to more than one extent), and does not delete any dependencies (for example, inner or embedded classes).
void DeleteClass(string className)
parameter:
If the specified class does not exist, the call silently fails (no error is thrown).
see also:
“Deleting Test Data” in Accessing Stored Events
DeleteExtent()
EventPersister.DeleteExtent() deletes the extent definition associated with a .NET event, but does not destroy associated data (since objects can belong to more than one extent). See Extents in Using Caché Objects for more information on managing extents.
void DeleteExtent(string className)
Do not confuse this method with the deprecated Event.DeleteExtent(), which destroys all extent data as well as with the extent definition.
see also:
“Deleting Test Data” in Accessing Stored Events
GetAdoConnection()
EventPersister.GetAdoNetConnection() returns the .NET DbConnection object underlying an EventPersister connection.
System.Data.Common.DbConnection GetAdoNetConnection()
see also:
Creating and Connecting an EventPersister
GetConnection()
EventPersister.GetConnection() — returns the instance of Intersystems.Globals.Connection underlying an EventPersister eXTreme connection. Throws an exception if the EventPersister has a TCP/IP connection.
Intersystems.Globals.Connection\1\2\3
see also:
Creating and Connecting an EventPersister
GetEvent()
EventPersister.GetEvent() returns an Event object that corresponds to the class name supplied, and optionally specifies the indexing mode to be used.
Event GetEvent(string className)
Event GetEvent(string className, int indexMode)
parameter:
The following indexMode options are available:
The same instance of Event can be used to store or retrieve all instances of a class, so a process should only call the GetEvent() method once per class. Avoid instantiating multiple Event objects for a single class, since this can affect performance and may cause memory leaks.
see also:
Creating Event Instances and Storing Persistent Events, Controlling Index Updating
GetInterfaceResolver()
EventPersister.GetInterfaceResolver() — returns the currently set instance of InterfaceResolver that will be used by ImportSchema() (see Implementing an InterfaceResolver). Returns null if no instance has been set.
InterfaceResolver GetInterfaceResolver()
see also:
SetInterfaceResolver(), ImportSchema()
GetTransactionLevel()
EventPersister.GetTransactionLevel() returns the current transaction level (0 if not in a transaction)
int GetTransactionLevel()
ImportSchema()
EventPersister.ImportSchema() produces a flat schema (see Schema Import Models) that embeds all referenced objects as serialized objects. The method imports the schema of each event declared in the class or a .dll file specified (including dependencies), and returns an array of class names for the imported events.
string[] ImportSchema(string classOrDLLName)
string[] ImportSchema(string[] classes)
parameters:
If the argument is a class name, the corresponding class and any dependencies will be imported. If the argument is a .dll file, all classes in the file and any dependencies will be imported. If such schema already exists, and it appears to be in sync with the .NET schema, import will be skipped. Should a schema already exist, but it appears different, a check will be performed to see if there is any data. If there is no data, a new schema will be generated. If there is existing data, an exception will be thrown.
see also:
Importing a Schema
ImportSchemaFull()
EventPersister.ImportSchemaFull() — produces a full schema (see Schema Import Models) that preserves the object hierarchy of the source classes. The method imports the schema of each event declared in the class or .dll file specified (including dependencies), and returns an array of class names for the imported events.
string[] ImportSchemaFull(string classOrDLLName)
string[] ImportSchemaFull(string[] classes)
parameters:
If the argument is a class name, the corresponding class and any dependencies will be imported. If the argument is a .dll file, all classes in the file and any dependencies will be imported. If such schema already exists, and it appears to be in sync with the .NET schema, import will be skipped. Should a schema already exist, but it appears different, a check will be performed to see if there is any data. If there is no data, a new schema will be generated. If there is existing data, an exception will be thrown.
see also:
Importing a Schema
Rollback()
EventPersister.Rollback() rolls back the specified number of levels of transaction, where level is a positive integer, or roll back all levels of transaction if no level is specified.
void Rollback()
void Rollback(int level)
parameter:
This method does nothing if level is less than 0, and stops rolling back once the transaction level reaches 0 if level is greater than the initial transaction level.
SetInterfaceResolver()
EventPersister.SetInterfaceResolver() — sets the instance of InterfaceResolver to be used by ImportSchema() (see Implementing an InterfaceResolver). All instances of Event created by this EventPersiser will share the specified InterfaceResolver (which defaults to null if this method is not called).
void SetInterfaceResolver(InterfaceResolver interfaceResolver)
parameters:
see also:
GetInterfaceResolver(), ImportSchema()
StartTransaction()
EventPersister.StartTransaction() starts a transaction (which may be a nested transaction)
void StartTransaction()
Class Event
Class InterSystems.XEP.Event provides methods that operate on XEP events (storing events, creating a query, indexing etc.). It is created by the EventPersister.GetEvent() method.
Close()
Event.Close() releases all resources held by this instance.
void Close()
It is important to always call Close() on an instance of Event before it goes out of scope. Failing to close it can cause serious memory leaks because .NET garbage collection cannot release resources allocated by the underlying native code.
CreateQuery()
Event.CreateQuery() takes a String argument containing the text of the SQL query and returns an instance of EventQuery<T>, where parameter T is the target class of the parent Event.
EventQuery<T> CreateQuery(string sqlText)
parameter:
see also:
Creating and Executing a Query
DeleteObject()
Event.DeleteObject() deletes an event identified by its database object ID or IdKey.
void DeleteObject(long id) 
void DeleteObject(object[] idkeys)
parameter:
see also:
Accessing Stored Events
GetObject()
Event.GetObject() fetches an event identified by its database object ID or IdKey. Returns null if the specified object does not exist.
object GetObject(long id) 
object GetObject(object[] idkeys)
parameter:
see also:
Accessing Stored Events
IsEvent()
Event.IsEvent() throws an XEPException if the object (or class) is not an event in the XEP sense (see Requirements for Imported Classes). The exception message will explain why the object is not an XEP event.
static void IsEvent(object objectOrClass)
parameter:
StartIndexing()
Event.StartIndexing() starts asynchronous index building for the extent of the target class. Throws an exception if the index mode is Event.INDEX_MODE_SYNC (see Controlling Index Updating).
void StartIndexing()
StopIndexing()
Event.StopIndexing() stops asynchronous index building for the extent. If you do not want the index to be updated when the Event instance is closed, call this method before calling Event.Close().
void StopIndexing()
see also:
Controlling Index Updating
Store()
Event.Store() stores a .NET object or array of objects as persistent events. There is no significant performance difference between passing an array and passing individual objects in a loop, but all objects in the array must be of the same type. Returns a long database ID for each newly inserted object, or 0 if the ID could not be returned or the event uses an IdKey.
long Store(object obj) 
long[] Store(object[] objects)
parameters:
UpdateObject()
Event.UpdateObject() updates an event identified by its database ID or IdKey.
void UpdateObject(long id, object obj) 
void UpdateObject(object[] idkeys, object obj)
parameter:
see also:
Accessing Stored Events
WaitForIndexing()
Event.WaitForIndexing() waits for asynchronous indexing to be completed, returning true if indexing has been completed, or false if the wait timed out before indexing was completed. Throws an exception if the index mode is Event.INDEX_MODE_SYNC.
bool WaitForIndexing(int timeout)
parameter:
see also:
Controlling Index Updating
Class EventQuery<>
Class InterSystems.XEP.EventQuery<> can be used to retrieve, update and delete individual events from the database.
AddParameter()
EventQuery<>.AddParameter() binds the next parameter in sequence for the SQL query associated with this EventQuery<>.
void AddParameter(object val)
parameter:
see also:
Creating and Executing a Query
Close()
EventQuery<>.Close() releases all resources held by this instance.
void Close()
It is important to always call Close() on an instance of EventQuery<> before it goes out of scope. Failing to close it can cause serious memory leaks because .NET garbage collection cannot release resources allocated by the underlying native code.
DeleteCurrent()
EventQuery<>.DeleteCurrent() deletes the event most recently fetched by GetNext().
void DeleteCurrent()
see also:
Processing Query Data
Execute()
EventQuery<>.Execute() executes the SQL query associated with this EventQuery<>. If the query is successful, this EventQuery<> will contain a resultset that can be accessed by other EventQuery<> methods.
void Execute()
see also:
Creating and Executing a Query
GetAll()
EventQuery<>.GetAll() returns objects of target class E from all rows in the resultset as a single list.
System.Collections.Generic.List<E> GetAll()
Uses GetNext() to get all target class E objects in the resultset, and returns them in a List. The list cannot be used for updating or deleting (although Event methods UpdateObject() and DeleteObject() can be used if you have some way of obtaining the Id or IdKey of each object). GetAll() and GetNext() cannot access the same resultset — once either method has been called, the other method cannot be used until Execute() is called again.
This method is more resource-intensive than a loop that explicitly calls GetNext() for each item, since there is a high cost associated with maintaining a list of objects.
see also:
Processing Query Data, Event.UpdateObject(), Event.DeleteObject()
GetFetchLevel()
EventQuery<>.GetFetchLevel() returns the current fetch level (see Defining the Fetch Level).
int GetFetchLevel()
GetNext()
EventQuery<>.GetNext() returns an object of target class E from the next row of the resultset. Returns null if there are no more items in the resultset.
E GetNext()
see also:
Processing Query Data
SetFetchLevel()
EventQuery<>.SetFetchLevel() controls the amount of data returned by setting a fetch level (see Defining the Fetch Level).
For example, by setting the fetch level to Event.FETCH_LEVEL_DATATYPES_ONLY, objects returned by this query will only have their datatype properties set, and any object type, array, or collection properties will not get populated. Using this option can dramatically improve query performance.
void SetFetchLevel(int level)
parameter:
Supported fetch levels are:
UpdateCurrent()
EventQuery<>.UpdateCurrent() updates the event most recently fetched by GetNext().
void UpdateCurrent(E obj)
parameter:
see also:
Processing Query Data
Interface InterfaceResolver
By default, properties declared as interfaces are ignored during schema generation. To change this behavior, an implementation of InterfaceResolver can be passed to the ImportSchema() method, providing it with information that allows it to replace an interface type with the correct concrete type.
GetImplementationClass()
InterfaceResolver.GetImplementationClass() returns the actual type of a property declared as an interface. See Implementing an InterfaceResolver for details.
Type GetImplementationType(Type declaringClass, string fieldName, Type interfaceClass)
parameters:
Class XEPException
Class InterSystems.XEP.XEPException implements the exception thrown by most methods of Event, EventPersister, and EventQuery<>. This class inherits methods and properties from System.SystemException.
Globals Quick Reference
This section is a reference for the Globals API (namespace Intersystems.Globals). See Using the Globals API for a details on how to use the API. It contains the following public classes:
Namespace InterSystems.Globals:
List of Globals API Methods
The following classes and methods of the Globals API are described in this reference:
Class ConnectionContext
Class Connection
Class GlobalsDirectory
Class NodeReference
Also see Acquiring and Releasing Locks in the chapter on Using the Globals API for a list of valid arguments used by the AcquireLock() and ReleaseLock(). See Controlling the Timeout Interval for more on the arguments used by SetOption(), and GetOption().
Class ValueList
Class ByteArrayRegion
Globals Exception Classes
Class ConnectionContext
Class InterSystems.Globals.ConnectionContext is required to create a Globals API Connection object. See the section on Creating a Connection in Using the Globals API for information on usage. See the help file, located in <install-dir>/dev/dotnet/help/CacheExtreme.chm, for more details on connection options.
ConnectionContext() Constructor
A protected constructor is defined to permit deriving classes from ConnectionContext.
ConnectionContext()
GetConnection()
ConnectionContext.GetConnection() creates an instance of InterSystems.Globals.Connection, or a specified class derived from Connection.
static Connection GetConnection()
static Connection GetConnection(string connectionClassName)
parameter:
Class Connection
Class InterSystems.Globals.Connection represents a connection to the Caché database. Instances of Connection are created by calls to the GetConnection() method of class ConnectionContext. All instances of Connection in a process reference the same underlying connection. Use Connection.IsConnected() to determine if the underlying connection already exists. See Creating a Connection for more information on how connections work.
Connection() Constructor
A protected constructor is defined to permit deriving classes from Connection.
Connection()
CallBytesClassMethod()
Connection.CallBytesClassMethod() — calls a ObjectScript class method and returns an Object that may be of type int, long, double, or byte[].
This method is identical to CallClassMethod() except that it returns string values as instances of byte[] rather than String.
Object CallBytesClassMethod(string className, string methodName, params Object[] args)
parameters:
CallBytesFunction()
Connection.CallBytesFunction() calls a ObjectScript function (see User-defined Code in Using Caché ObjectScript) and returns an Object that may be of type int, long, double, or byte[].
This method is identical to CallFunction() except that it returns string values as instances of byte[] rather than String.
Object CallBytesFunction(string functionName, string routineName, params Object[] args)
parameters:
CallClassMethod()
Connection.CallClassMethod() — calls a ObjectScript class method and returns an Object that may be of type int, long, double, or String. Use CallVoidClassMethod() to call a method that doesn’t return a value, CallBytesClassMethod() to return string values as byte[], or CallListClassMethod() to return string values as ValueList.
Object CallClassMethod(string className, string methodName, params Object[] args)
parameters:
CallFunction()
Connection.CallFunction() — calls a ObjectScript function (see User-defined Code in Using Caché ObjectScript) and returns an Object that may be of type int, long, double, or String. Use CallBytesFunction() to return string values as byte[], or CallListFunction() to return string values as ValueList.
Object CallFunction(string functionName, string routineName, params Object[] args)
parameters:
CallListClassMethod()
Connection.CallListClassMethod() — calls a ObjectScript class method and returns an Object that may be of type int, long, double, or ValueList.
This method is identical to CallClassMethod() except that it returns string values as instances of ValueList rather than String.
Object CallListClassMethod(string className, string methodName, params Object[] args)
Throws an exception if the return value is a string but is not in valid ValueList format.
parameters:
CallListFunction()
Connection.CallListFunction() calls a ObjectScript function (see User-defined Code in Using Caché ObjectScript) and returns an Object that may be of type int, long, double, or ValueList.
This method is identical to CallFunction() except that it returns string values as instances of ValueList rather than String.
Object CallListFunction(string functionName, string routineName, params Object[] args)
Throws an exception if the return value is a string but is not in valid ValueList format.
parameters:
CallProcedure()
Connection.CallProcedure() calls a ObjectScript procedure (see User-defined Code in Using Caché ObjectScript).
void CallProcedure(string procedureName, string routineName, params Object[] args)
parameters:
CallVoidClassMethod()
Connection.CallVoidClassMethod() — calls a ObjectScript class method with no return value, passing 0 or more arguments. This method may be used to call any Caché class method (regardless of whether it normally returns a value) when the caller does not need the return value. Use CallClassMethod() to call a method that returns a value.
void CallVoidClassMethod(string className, string methodName, params Object[] args)
parameters:
Close()
Connection.Close() releases all resources held by this instance.
virtual void Close()
It is important to always call Close() on an instance of Connection before it goes out of scope. Failing to close it can cause serious memory leaks because .NET garbage collection cannot release resources allocated by the underlying native code.
Commit()
Connection.Commit() commits one level of transaction (see TransactionLevel()) for the current session.
virtual void Commit()
If the level is greater than 1, the current transaction is merged with the enclosing transaction, and can still be rolled back by calling Rollback(). When the transaction level is 1, any changes made during the transaction are permanently commited.
Connect()
Connection.Connect() connects the Connection object to the specified database. GlobalsException is thrown if the object is already connected.
virtual void Connect()
virtual void Connect(string namespc, string user, string password)
parameters:
If no arguments are specified, method call defaults to Connect("User","",""). This method uses the GLOBALS_HOME environment variable to locate the Caché instance (see Required Environment Variables and References).
CreateGlobalsDirectory()
Connection.CreateGlobalsDirectory() creates a browsable directory of the global names in the current namespace, with the cursor positioned before the first global name in collating sequence.
virtual GlobalsDirectory CreateGlobalsDirectory()
CreateList()
Connection.CreateList() returns a ValueList object, and optionally specifies a buffer size.
virtual ValueList CreateList()
virtual ValueList CreateList(int bufferSize)
parameter:
If bufferSize is not specified, the ValueList is created with a 1 kbyte buffer, which grows if needed but never gets smaller. Specifying a smaller bufferSize may save memory if a list is known to need significantly less than 1 kbyte. Specifying a larger bufferSize may enhance performance by avoiding repeated reallocation to grow the buffer, if a list is known to need significantly more than 1 kbytes.
CreateNodeReference()
Connection.CreateNodeReference() returns a NodeReference object, and optionally specifies the name of the global to be referenced.
virtual NodeReference CreateNodeReference()
virtual NodeReference CreateNodeReference(string name)
parameter:
If name is not specified, the node reference object's SetName() method must be called in order to specify a global array (see Setting and Changing Global Names).
GetNamespace()
Connection.GetNamespace() returns the name of the currently connected namespace.
string GetNamespace()
Throws GlobalsException if called when this instance is not connected.
GetProductVersion()
Connection.GetProductVersion() returns the version number of the connected Caché instance.
string GetProductVersion()
IsConnected()
Connection.IsConnected() returns true if this object is connected to a database.
bool IsConnected()
ReleaseAllLocks()
Connection.ReleaseAllLocks() releases all locks currently held in this connection
virtual void ReleaseAllLocks()
see also: Transactions and Locking
Rollback()
Connection.Rollback() rolls back levelCount levels of transaction, or roll back all levels of transaction if levelCount is not specified.
virtual void Rollback()
virtual void Rollback(int levelCount)
parameter:
Stops rolling back once transaction level reaches 0, if levelCount is greater than initial transaction level. Does nothing if levelCount is less than 1.
see also: Transactions and Locking
SetNamespace()
Connection.SetNamespace() sets the current namespace
virtual void SetNamespace(string namespc)
parameter:
StartTransaction()
Connection.StartTransaction() starts a transaction (which may be a nested transaction).
virtual void StartTransaction()
see also: Transactions and Locking
TransactionLevel()
Connection.TransactionLevel() returns an int that indicates current transaction level (0 if not in a transaction).
virtual int TransactionLevel()
see also: Transactions and Locking
Class GlobalsDirectory
Class InterSystems.Globals.GlobalsDirectory represents a browsable directory of the names of globals in the current namespace. Global names may be browsed in ascending or descending collating sequence. These names may be passed to Connection.CreateNodeReference(string) to create instances of NodeReference that can be used to perform operations on globals.
Instances of GlobalsDirectory are created by calling the Connection.CreateGlobalsDirectory() method, or by using the GlobalsDirectory() constructor.
GlobalsDirectory() Constructor
A protected constructor is defined to permit deriving classes from GlobalsDirectory.
GlobalsDirectory()
Close()
GlobalsDirectory.Close() releases all resources held by this instance.
virtual void Close()
It is important to always call Close() on an instance of GlobalsDirectory before it goes out of scope. Failing to close it can cause serious memory leaks because .Net garbage collection cannot release resources allocated by the underlying native code.
NextGlobalName()
GlobalsDirectory.NextGlobalName() returns the next global name in collating sequence after the specified name (or after the current position if no global name is specified). Returns an empty string if there is no next name.
virtual string NextGlobalName()
virtual string NextGlobalName(string globalName)
parameter:
PreviousGlobalName()
GlobalsDirectory.PreviousGlobalName() returns the previous global name in collating sequence before the specified name (or before the current position if no global name is specified). Returns an empty string if there is no previous name.
virtual string PreviousGlobalName()
virtual string PreviousGlobalName(string globalName)
parameter:
refresh
GlobalsDirectory.Refresh() updates the list of global names, adding or deleting names to reflect any changes made since the instance was created or Refresh() was last called.
virtual void Refresh()
Class NodeReference
Class InterSystems.Globals.NodeReference represents a reference to a global node. It provides methods for specifying the node's name and subscripts, as well as methods to manipulate the node, including setting and getting its value, killing it, determining its state, and incrementing its value.
Instances of NodeReference are created by calls to the Connection CreateNodeReference() method. See the chapter on Using the Globals API for information on usage.
NodeReference() Constructor
A protected constructor is defined to permit deriving classes from NodeReference.
NodeReference()
AcquireLock()
NodeReference.AcquireLock() locks an object, using the specified locking arguments.
virtual void AcquireLock(int lockType, int lockMode)
virtual void AcquireLock(int lockType, int lockMode, params Object[] subscripts)
parameters:
see also: Transactions and Locking
AppendSubscript()
NodeReference.AppendSubscript() adds a new subscript at the end of the subscript list of a node reference object.
virtual void AppendSubscript(int subscriptValue)
virtual void AppendSubscript(long subscriptValue)
virtual void AppendSubscript(double subscriptValue)
virtual void AppendSubscript(string subscriptValue)
parameter:
For example, the method could add subscript "a" to ^myGlobal(1), changing the reference to ^myGlobal(1,"a").
Close()
NodeReference.Close() releases all resources held by this instance.
virtual void Close()
It is important to always call Close() on an instance of NodeReference before it goes out of scope. Failing to close it can cause serious memory leaks because .NET garbage collection cannot release resources allocated by the underlying native code.
Exists()
Deprecated: replaced by HasData().
NodeReference.Exists() returns true if the node has data. Returns false if the node is valueless or does not exist.
virtual bool Exists()
virtual bool Exists(params Object[] subscripts)
parameter:
GetBytes()
NodeReference.GetInt() returns the value of this node as a byte[]. A null is returned if the referenced node is valueless or does not exist.
virtual byte[] GetBytes()
virtual byte[] GetBytes(params Object[] subscripts)
parameter:
GetDouble()
NodeReference.GetDouble() returns the value of this node as a double. This method should never be used if the node value might be a String.
virtual double GetDouble()
virtual double GetDouble(params Object[] subscripts)
parameter:
String values are not converted even if they are numeric. The method will attempt to interpret the string as a valid double, and will return a meaningless and unpredictable value.
Throws UndefinedException if the referenced node is valueless or does not exist.
GetDoubleSubscript()
NodeReference.GetDoubleSubscript() reads the subscript specified by subscriptPosition and returns it as a double value.
virtual double GetDoubleSubscript(int subscriptPosition)
parameter:
Throws GlobalsException if subscriptPosition is greater than the current number of subscripts, or if the subscript is the wrong datatype.
GetInt()
NodeReference.GetInt() returns the value of this node as an int.
virtual int GetInt()
virtual int GetInt(params Object[] subscripts)
parameter:
If the node value was originally set as a double, the returned value will be truncated to a long value. If the node value is a non-numeric string (one that does not start with +, -, or a digit), a 0 will be returned.
Throws UndefinedException if the referenced node is valueless or does not exist.
GetIntSubscript()
NodeReference.GetIntSubscript() reads the subscript specified by subscriptPosition and returns it as an int value.
virtual int GetIntSubscript(int subscriptPosition)
parameter:
Throws GlobalsException if subscriptPosition is greater than the current number of subscripts, or if the subscript is the wrong datatype.
GetList()
NodeReference.GetList() returns the value of this node as a ValueList. A null is returned if the referenced node is valueless or does not exist.
virtual ValueList GetList()
virtual ValueList GetList(params Object[] subscripts)
virtual ValueList GetList(ValueList reuseList)
virtual ValueList GetList(ValueList reuseList, params Object[] subscripts)
parameter:
Throws GlobalsException if the value is not a string in valid $LIST format.
GetLong()
NodeReference.GetLong() returns the value of this node as a long.
virtual long GetLong()
virtual long GetLong(params Object[] subscripts)
parameter:
Throws UndefinedException if the referenced node is valueless or does not exist.
GetLongSubscript()
NodeReference.GetLongSubscript() reads the subscript specified by subscriptPosition and returns it as a long value.
virtual long GetLongSubscript(int subscriptPosition)
parameter:
Throws GlobalsException if subscriptPosition is greater than the current number of subscripts, or if the subscript is the wrong datatype (int values are permitted).
GetName()
NodeReference.GetName() returns the name of the global array containing this node.
virtual string GetName()
GetObject()
NodeReference.GetObject() returns the node value as an Object, which will be an instance of int, long, double, or String (instances of byte[] and ValueList are returned as instances of String). Returns null if the node is valueless.
virtual Object GetObject()
virtual Object GetObject(params Object[] subscripts)
parameter:
GetObjectSubscript()
NodeReference.GetObjectSubscript() returns the subscript specified by subscriptPosition as an Object, which will be an instance of int, long, double, or String.
virtual Object GetObjectSubscript(int subscriptPosition)
Throws GlobalsException if subscriptPosition is greater than current number of subscripts.
GetOption()
NodeReference.GetOption() returns the current lock timeout setting (see SetOption()).
int GetOption(int option)
parameter:
see also: Transactions and Locking
GetString()
NodeReference.GetString() returns the value of this node as a String. A null is returned if the referenced node is valueless or does not exist.
virtual string GetString()
virtual string GetString(params Object[] subscripts)
parameter:
Any global value can be accessed as a string, although the string may be meaningless or misleading in the context of your application. For example, if a node is set to a double value of 19.95, the string returned by this method will be 19.949999999999999289, which is the internal representation of the double.
GetStringSubscript()
NodeReference.GetStringSubscript() reads the subscript specified by subscriptPosition and returns it as a String value.
virtual string GetStringSubscript(int subscriptPosition)
parameter:
Throws GlobalsException if subscriptPosition is greater than the current number of subscripts, or if the subscript is the wrong datatype.
GetSubscriptCount()
NodeReference.GetSubscriptCount() returns an int that indicates the current number of subscripts
virtual int GetSubscriptCount()
For example, if the node reference points to ^myGlobal(1,"a"), the method returns 2.
HasData()
NodeReference.HasData() returns true if the node has data. Returns false if the node is valueless or does not exist.
virtual bool HasData()
virtual bool HasData(params Object[] subscripts)
parameter:
HasSubnodes()
NodeReference.HasSubnodes() returns true if the referenced node has descendants.
virtual bool HasSubnodes()
virtual bool HasSubnodes(params Object[] subscripts)
parameter:
Increment()
NodeReference.Increment() increments or decrements the value of the current node by the specified int value, and returns the new value as a long. If the incremented node value is a double, the returned value will be truncated. This is an atomic operation (lock-free, thread-safe).
virtual long Increment(int number)
virtual long Increment(int number, params Object[] subscripts)
parameter:
If no node exists at the current reference, a node with a value of 0 is created and incremented.
Kill()
NodeReference.Kill() deletes the node at the current node reference and all of its descendants.
virtual void Kill()
virtual void Kill(params Object[] subscripts)
parameter:
This method is equivalent to the Caché KILL command.
KillNode()
NodeReference.KillNode() deletes the value of the node at the current node reference, but does not affect its subnodes. If the node does not have subnodes, it is deleted from the database.
virtual void KillNode()
virtual void KillNode(params Object[] subscripts)
parameter:
This method is equivalent to the Caché ZKILL command.
NextSubscript()
NodeReference.NextSubscript() returns a String containing the subscript of the next node in collation order on the current level. Returns an empty string ("") if there is no next subscript.
virtual string NextSubscript()
virtual string NextSubscript(params Object[] subscripts)
parameter:
PreviousSubscript()
NodeReference.PreviousSubscript() returns a String containing the subscript of the previous node in collation order on the current level. Returns an empty string ("") if there is no previous subscript.
virtual string PreviousSubscript()
virtual string PreviousSubscript(params Object[] subscripts)
parameter:
ReleaseLock()
NodeReference.ReleaseLock() releases the lock on the current node.
virtual void ReleaseLock(int lockType, int releaseMode)
virtual void ReleaseLock(int lockType, int releaseMode, params Object[] subscripts)
parameter:
see also: Transactions and Locking, Connection.ReleaseAllLocks()
Set()
NodeReference.Set() assigns the specified value to the referenced node.
virtual void Set(int value)
virtual void Set(int value, params Object[] subscripts)
virtual void Set(long value)
virtual void Set(long value, params Object[] subscripts)
virtual void Set(double value)
virtual void Set(double value, params Object[] subscripts)
virtual void Set(string value)
virtual void Set(string value, params Object[] subscripts)
virtual void Set(byte[] value)
virtual void Set(byte[] value, params Object[] subscripts)
void Set(ValueList list)
void Set(ValueList list, params Object[] subscripts)
parameter:
If no persistent node exists at the current reference, a new one is created and set to the specified value.
SetName()
NodeReference.SetName() specifies the name of the global to be referenced by this node object.
virtual void SetName(string name)
parameter:
SetOption()
NodeReference.SetOption() sets the number of seconds that AcquireLock() should wait for a lock before timing out. Other options will be added in future releases.
void SetOption(int option, int value)
parameter:
SetSubscript()
NodeReference.SetSubscript() changes the specified subscript, or adds a new subscript.
virtual void SetSubscript(int subscriptPosition, double value)
virtual void SetSubscript(int subscriptPosition, int value)
virtual void SetSubscript(int subscriptPosition, long value)
virtual void SetSubscript(int subscriptPosition, string value)
parameter:
For example, if the node reference pointed to ^myGlobal(1,"a"), a call to SetSubscript(1,8) would set the reference to ^myGlobal(8,"a").
This method is equivalent to AppendSubscript() if subscriptPosition is equal to GetSubscriptCount()+1. For example, a call to SetSubscript(3,"x") would set it to ^myGlobal(1,"a","x").
If subscriptPosition is less than 1, a value of 1 will be used.
Throws GlobalsException if subscriptPosition is greater than GetSubscriptCount()+1.
SetSubscriptCount()
NodeReference.SetSubscriptCount() shortens the subscript list by removing all subscripts after the one specified by num.
void SetSubscriptCount(int number)
parameter:
For example, if the reference points to ^myGlobal(1,"a",35), calling SetSubscriptCount(1) would remove all subscripts except the first, changing the reference to ^myGlobal(1).
Throws GlobalsException if num is greater than the current number of subscripts.
Class ValueList
Class InterSystems.Globals.ValueList encapsulates a .NET representation of a simple Caché $LIST object. The following datatypes and their associated System types are supported: int, long, double, String, byte[], and nested instances of ValueList. See Storing Multiple Items in a Node with ValueList for information on usage. ValueList objects are created by calling the Connection.CreateList() method, or by using ValueList() constructors.
ValueList() Constructors
Creates an empty ValueList instance, optionally specifying the initial buffer size.
ValueList()
ValueList(int bufferSize)
parameter:
The bufferSize parameter permits optional tuning of the amount of memory used for a list's underlying implementation. By default, a ValueList is created with a 1 kbyte buffer, which grows if needed but never gets smaller. Specifying a smaller bufferSize may save memory if a list is known to need significantly less than 1 kbytes. Specifying a larger bufferSize may enhance performance by avoiding repeated reallocation to grow the buffer, if a list is known to need significantly more than 1 kb.
Throws GlobalsException if a Connection to the globals database has not been established.
Append()
ValueList.Append() appends a value of the specified datatype to the list.
virtual void Append(byte[] value)
virtual void Append(double value)
virtual void Append(int value)
virtual void Append(long value)
virtual void Append(string value)
virtual void Append(ValueList list)
Multiple values can be specified in a single call to Append():
virtual void Append(params Object[] values)
parameter:
Throws GlobalsException if the argument is an invalid datatype.
Clear()
ValueList.Clear() clears the list, causing it to contain 0 items.
virtual void Clear()
Throws GlobalsException.
Close()
ValueList.Close() releases all resources held by this instance.
virtual void Close()
It is important to always call Close() on an instance of ValueList before it goes out of scope. Failing to close it can cause serious memory leaks because .NET garbage collection cannot release resources allocated by the underlying native code.
Throws GlobalsException if the instance of ValueList calls any other method after this one.
GetAll()
ValueList.GetAll() returns all items from the list as an array of Object, or returns null if the list is empty. Each returned Object is an instance of int, long, double, String, or byte[], depending on the type and value of the item in the list. An Object is null if the corresponding list item is null. This method leaves the list cursor positioned beyond last item in the list.
virtual object GetAll()[]
virtual object GetAll(bool returnBytes)[]
parameter:
Throws GlobalsException.
GetNextBytes()
ValueList.GetNextBytes() returns the next item from the list as byte[]. Returns null if list item is null.
virtual byte GetNextBytes()[]
Throws GlobalsException if the cursor is already at the end of the list.
GetNextDouble()
ValueList.GetNextDouble() returns the next item from the list as a double. Returns 0 if list item is null.
virtual double GetNextDouble()
Throws GlobalsException if the cursor is already at the end of the list.
GetNextInt()
ValueList.GetNextInt() returns the next item from the list as an int. Returns 0 if list item is null.
virtual int GetNextInt()
Throws GlobalsException if the cursor is already at the end of the list.
GetNextList()
ValueList.GetNextList() returns the next item from the list as a ValueList. Returns null if list item is null.
virtual ValueList GetNextList()
virtual ValueList GetNextList(ValueList reuseList)
parameter:
Throws GlobalsException if the cursor is already at the end of the list, or if the list item is not a valid ValueList.
GetNextLong()
ValueList.GetNextLong() returns the next item from the list as a long. Returns 0 if list item is null.
virtual long GetNextLong()
Throws GlobalsException if the cursor is already at the end of the list.
GetNextObject()
ValueList.GetNextObject() returns the next item from the list as an Object. The type of the returned object depends on the type and value of the item in the list, and on the setting of the optional returnBytes parameter.
A null is returned if the list item is null. All integer values are returned as int if they are within the range of int, else they are returned as long. Double values are always returned as double. If optional returnBytes is specified as true, both byte[] and String are returned as byte[]. If it is false or not specified, both types are returned as String.
virtual Object GetNextObject()
virtual Object GetNextObject(bool returnBytes)
parameter:
Throws GlobalsException if the cursor is already at the end of the list.
GetNextString()
ValueList.GetNextString() returns the next item from the list as a String. Returns null if list item is null.
virtual string GetNextString()
Throws GlobalsException if the cursor is already at the end of the list.
Length property
ValueList.Length [get] returns the number of items in the list.
virtual int Length [get]
Throws GlobalsException.
ResetToFirst()
ValueList.ResetToFirst() resets the cursor to the beginning of the list.
virtual void ResetToFirst()
Throws GlobalsException.
SkipNext()
ValueList.SkipNext() advances the cursor past the number of list items specified by count without getting their values.
virtual void SkipNext(int count)
parameter:
Throws GlobalsException if fewer than count items remain in the list beyond the cursor position.
Class ByteArrayRegion
Class InterSystems.Globals.ByteArrayRegion specifies a region of a byte array, encapsulating the source array, the starting offset, and the length of the region. This class provides a convenient and efficient way to pass a byte array region as an argument to the Connection methods that call ObjectScript methods and functions (see Calling Caché Methods) without having to copy the region to a separate byte[] instance.
ByteArrayRegion() Constructors
Create a new instance of ByteArrayRegion. Can optionally specify the source array, offset, and number of bytes in the region.
ByteArrayRegion()
ByteArrayRegion(byte[] sourceArray, int offset, int length)
parameters:
Length property
ByteArrayRegion.Length [get, set] gets the number of bytes in the region or sets the number of bytes to be included in the region.
virtual int Length [get, set]
Offset property
ByteArrayRegion.Offset [get, set] gets the starting offset of the region within the source array or sets the starting offset of the region.
virtual int Offset [get, set]
Set()
ByteArrayRegion.Set() defines all attributes of the region.
void Set(byte[] sourceArray, int offset, int length)
parameter:
SourceArray property
ByteArrayRegion.SourceArray [get, set] gets or sets the source array containing the region.
virtual byte[] SourceArray [get, set]
Globals Exception Classes
The Globals API implements the following exceptions:
Class GlobalsException
Class InterSystems.Globals.GlobalsException implements an exception thrown by all classes of the Globals API. This class inherits methods and properties from System.Exception. The ErrorCode property provides error information specific to the Globals API.
Constructors
In addition to the parameters defined for System.Exception constructors, the GlobalsException constructors provide an error code parameter for errors specific to the Globals API:
GlobalsException(string message)
GlobalsException(string message, int errorcode)
parameters:
ErrorCode property
Returns a numeric error code that can be used to distinguish some specific Globals API errors. Error code UNDEFINED means that no specific error code is defined for this situation.
virtual int ErrorCode { get; }
The following error codes are defined:
Class LockException
Class InterSystems.Globals.LockException implements an exception thrown by NodeReference method AcquireLock(). It is thrown if a request to acquire a lock fails, due to timing out waiting for the lock to become available. See Transactions and Locking for information on usage.
Constructors
  LockException()
  LockException(string message)
parameters:
This class inherits from GlobalsException. The inherited ErrorCode property provides error information specific to the Globals API.
Class UndefinedException
Class InterSystems.Globals.UndefinedException implements an exception thrown by methods that get the value of a node. The exception is thrown if the referenced node is valueless or does not exist.
Constructor
UndefinedException()
UndefinedException(string msg)
parameters:
This class inherits from GlobalsException. The inherited ErrorCode property provides error information specific to the Globals API.