Quick Reference for eXTreme Classes - Using .NET with Caché eXTreme

CallBytesClassMethod() — calls a Caché class method, returning strings as byte[].
CallBytesFunction() — calls a Caché function, returning strings as byte[].
CallClassMethod() — calls a Caché class method.
CallFunction() — calls a Caché function.
CallListClassMethod() — calls a Caché class method, returning strings as ValueList.
CallListFunction() — calls a Caché function, returning strings as ValueList.
CallProcedure() — calls a Caché procedure.
CallVoidClassMethod() — calls a Caché class method with no return value.
Close() — releases all resources held by this instance.
Commit() — commits one level of transaction.
Connect() — connects to Caché using the arguments specified.
DeleteClass() — deletes a Caché class.
DeleteExtent() — deletes all objects in the given extent.
GetConnection() — Returns the underlying eXTreme connection.
GetAdoNetConnection() — returns the .NET DbConnection object.
GetEvent() — returns an event object that corresponds to the class name supplied.
GetInterfaceResolver() — returns the currently specified instance of InterfaceResolver.
GetTransactionLevel() — returns the current transaction level (or 0 if not in a transaction).
ImportSchema() — imports a flat schema.
ImportSchemaFull() — imports a full schema.
Rollback() — rolls back the specified number of transaction levels, or all levels if no level is specified.
SetInterfaceResolver() — specifies the InterfaceResolver object to be used.
StartTransaction() — starts a transaction (which may be a nested transaction).

Close() — releases all resources held by this instance.
CreateQuery() — creates a EventQuery<> instance.
DeleteObject() — deletes an event given its database Id or IdKey.
GetObject() — returns an event given its database Id or IdKey.
IsEvent() — checks whether an object (or class) is an event in the XEP sense.
StartIndexing() — starts index building for the underlying class.
StopIndexing() — stops index building for the underlying class.
Store() — stores the specified object or array of objects.
UpdateObject() — updates an event given its database Id or IdKey.
WaitForIndexing() — waits for asynchronous indexing to be completed for this class.

AddParameter() — binds a parameter for this query.
Close() — releases all resources held by this instance.
DeleteCurrent() — deletes the event most recently fetched by GetNext().
Execute() — executes this XEP query.
GetAll() — fetches all events in the resultset as an array.
GetFetchLevel() — returns the current fetch level.
GetNext() — fetches the next event in the resultset.
SetFetchLevel() — controls the amount of data returned.
UpdateCurrent() — updates the event most recently fetched by GetNext()

GetImplementationClass() — if a property was declared as an interface, an implementation of this method can be used to resolve the actual property type during schema importation.

Creates a new instance of PersisterFactory.

PersisterFactory()

PersisterFactory.CreatePersister() returns an instance of EventPersister.

static EventPersister CreatePersister()

EventPersister.CallBytesClassMethod() — calls an 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:

className — fully qualified name of the Caché class to which the called method belongs.
methodName — name of the Caché class method.
args — a list of 0 or more arguments to pass to the class method.

Arguments may be of type int, long, double, String, byte[], ValueList, or Globals.ByteArrayRegion. Trailing arguments may be omitted, causing default values to be used for those arguments, either by passing fewer than the full number of arguments, or by passing null for trailing arguments. Throws an exception if a non-null argument is passed to the right of a null argument.

EventPersister.CallBytesFunction() calls an 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:

functionName — name of the function.
routineName — name of the routine containing the function.
args — a list of 0 or more arguments to pass to the function.

Arguments may be of type int, long, double, String, byte[], ValueList, or Globals.ByteArrayRegion. Trailing arguments may be omitted, causing default values to be used for those arguments, either by passing fewer than the full number of arguments, or by passing null for trailing arguments. Throws an exception if a non-null argument is passed to the right of a null argument.

EventPersister.CallClassMethod() — calls an 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:

className — fully qualified name of the Caché class to which the called method belongs.
methodName — name of the Caché class method.
args — a list of 0 or more arguments to pass to the class method.

Arguments may be of type int, long, double, String, byte[], ValueList, or Globals.ByteArrayRegion. Trailing arguments may be omitted, causing default values to be used for those arguments, either by passing fewer than the full number of arguments, or by passing null for trailing arguments. Throws an exception if a non-null argument is passed to the right of a null argument.

EventPersister.CallFunction() — calls an 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:

functionName — name of the function.
routineName — name of the routine containing the function.
args — a list of 0 or more arguments to pass to the function.

Arguments may be of type int, long, double, String, byte[], ValueList, or Globals.ByteArrayRegion. Trailing arguments may be omitted, causing default values to be used for those arguments, either by passing fewer than the full number of arguments, or by passing null for trailing arguments. Throws an exception if a non-null argument is passed to the right of a null argument.

EventPersister.CallListClassMethod() — calls an 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:

className — fully qualified name of the Caché class to which the called method belongs.
methodName — name of the Caché class method.
args — a list of 0 or more arguments to pass to the class method.

Arguments may be of type int, long, double, String, byte[], ValueList, or Globals.ByteArrayRegion. Trailing arguments may be omitted, causing default values to be used for those arguments, either by passing fewer than the full number of arguments, or by passing null for trailing arguments. Throws an exception if a non-null argument is passed to the right of a null argument.

EventPersister.CallListFunction() calls an 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:

functionName — name of the function.
routineName — name of the routine containing the function.
args — a list of 0 or more arguments to pass to the function.

Arguments may be of type int, long, double, String, byte[], ValueList, or Globals.ByteArrayRegion. Trailing arguments may be omitted, causing default values to be used for those arguments, either by passing fewer than the full number of arguments, or by passing null for trailing arguments. Throws an exception if a non-null argument is passed to the right of a null argument.

EventPersister.CallProcedure() calls an ObjectScript procedure (see “User-defined Code” in Using Caché ObjectScript).

void CallProcedure(string procedureName, string routineName, params Object[] args)

parameters:

procedureName — name of the procedure.
routineName — name of the routine containing the procedure.
args — a list of 0 or more arguments to pass to the procedure.

Arguments may be of type int, long, double, String, byte[], ValueList, or Globals.ByteArrayRegion. Trailing arguments may be omitted, causing default values to be used for those arguments, either by passing fewer than the full number of arguments, or by passing null for trailing arguments. Throws an exception if a non-null argument is passed to the right of a null argument.

EventPersister.CallVoidClassMethod() — calls an 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:

className — fully qualified name of the Caché class to which the called method belongs.
methodName — name of the Caché class method.
args — a list of 0 or more arguments to pass to the class method.
Arguments may be of any of the types String, int, long, double, byte[], or Globals.ByteArrayRegion. Trailing arguments may be omitted, causing default values to be used for those arguments, either by passing fewer than the full number of arguments, or by passing null for trailing arguments. Throws an exception if a non-null argument is passed to the right of a null argument.

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.

EventPersister.Commit() commits one level of transaction

void Commit()

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:

nmspace — namespace to be accessed.
username — username for this connection.
password — password for this connection.
host — host address for TCP/IP connection.
port — port number for TCP/IP connection.

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:

className — name of the class to be deleted.

If the specified class does not exist, the call silently fails (no error is thrown).

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)

className — name of the extent.

Do not confuse this method with the deprecated Event.DeleteExtent(), which destroys all extent data as well as with the extent definition.

EventPersister.GetAdoNetConnection() returns the .NET DbConnection object underlying an EventPersister connection.

System.Data.Common.DbConnection GetAdoNetConnection()

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

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:

className — class name of the object to be returned.
indexMode — indexing mode to be used.

The following indexMode options are available:

Event.INDEX_MODE_ASYNC_ON — enables asynchronous indexing. This is the default when the indexMode parameter is not specified.
Event.INDEX_MODE_ASYNC_OFF — no indexing will be performed unless the StartIndexing() method is called.
Event.INDEX_MODE_SYNC — indexing will be performed each time the extent is changed, which can be inefficient for large numbers of transactions. This index mode must be specified if the class has a user-assigned IdKey.

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.

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()