Skip to main content
Previous sectionNext section

Using the Caché Dynamic Binding

The Caché dynamic binding allows an application to access Caché objects on the server without first generating proxy classes (described in “Using the Caché Object Binding for .NET”). Instead, a dynamic proxy class, CacheObject, can be created at runtime and used to access properties and call methods by name. Argument values and return types are specified by creating instances of the CacheMethodSignature class.

The dynamic binding can be useful for writing generic tools, and can be used as an alternative to regenerating proxy classes whenever a Caché class changes on the server.

This chapter covers the following topics:

Using Dynamic Objects

The examples in this chapter assume that a connection to the database has already been established through a CacheConnection object named conn (see “Connecting to the Caché Database” for more information about CacheConnection). Before dynamic objects can be used, the connection object's DynamicMode property must be set to true:

   conn.DynamicMode = true;
Copy code to clipboard

A new InterSystems.Data.CacheTypes.CacheObject can be created with a statement such as the following:

   CacheObject dynamicObj = new CacheObject(conn, className);
Copy code to clipboard

where conn is an open CacheConnection object, and className is a string containing the complete name of the class to be accessed.

Using Method Signature Objects

Before you can use a CacheObject instance to call a method, you must create a CacheMethodSignature object. The method signature object is used to specify the values of any arguments that are to be passed to the method, and the datatype of the method return value.

Use the GetMtdSignature() method of the connection object to create a CacheMethodSignature object:

   CacheMethodSignature mtdSignature = conn.GetMtdSignature()
Copy code to clipboard

The Add() and SetReturnType() methods of the CacheMethodSignature object are used to define the signature:

  • Use the Add() method to specify the values that will be passed as arguments to the method. Call Add() once for each argument to be passed. The method is called as follows:

       mtdSignature.Add(value, isByRef);
    Copy code to clipboard

    where value is a value of the appropriate type, and isByRef is a boolean that specifies whether or not the argument is passed by reference.

  • If the method returns a value, use the SetReturnType() method to specify the return type:

       SetReturnType(conn, typeId)
    Copy code to clipboard

    where typeId is one of the constants of the ClientTypeId enumeration.

After the CacheMethodSignature object has been used to call a method, the ReturnValue and Arguments properties can be used to retrieve the results.

  • The ReturnValue property will contain a value of the type specified by SetReturnType().

  • The Arguments property will contain an array with one element for each argument specified by Add(). Each element contains the current value of an argument (including arguments passed by reference).

A method signature object can be used for more than one call. Use the Clear() method to reinitialize the object before using Add() and SetReturnType() again to define the new signature.

Calling Methods

The RunMethod() and RunClassMethod() methods of CacheObject are used to make method calls:

  • For an instance method, the call is:

       dynamicObj.RunMethod(methodName, mtdSignature);
    Copy code to clipboard
  • For a class method, the call is:

       CacheObject.RunClassMethod(conn, className, methodName, mtdSignature);
    Copy code to clipboard

After the method has been called, any returned values can be retrieved from the Arguments and ReturnValue properties of the CacheMethodSignature object (as described in “Using Method Signature Objects”). The returned values must be cast to the appropriate type for the container object. For example the following line gets an integer return value and casts it to class CacheIntReturnValue:

   long? mtdRes = ((CacheIntReturnValue)(mtdSignature.ReturnValue)).Value;
Copy code to clipboard

The following line accesses the Arguments array to retrieve the current value of a string argument passed by reference, and casts it to class CacheStringArgument:

   response = ((CacheStringArgument)(mtdSignature.Arguments[1])).Value;
Copy code to clipboard

A complete description of the available Cache(type)Argument and Cache(type)ReturnValue classes can be found in the InterSystems.Data.CacheTypes namespace section of the Caché .NET Help File.

Accessing Properties

CacheMethodSignature objects are also used to specify property signatures. Once the signature has been specified, the GetProperty() and SetProperty() methods of the CacheObject object can be used to access the property value. For example, the following code specifies a signature that will be used for the Name property of a Sample.Person object, and then sets the property to the specified value:

   CacheMethodSignature mtdSignature = conn.GetMtdSignature();
   string value = "Smith, Wilbur"
   mtdSignature.Add(value, false);

   string propertyName = "Name"
   person.SetProperty(propertyName, mtdSignature);
Copy code to clipboard

The following code redefines the method signature, and then retrieves the value of the property:

   mtdSignature.Clear();
   mtdSignature.SetReturnType(conn, ClientTypeId.tString);
   person.GetProperty(propertyName, mtdSignature);
   string newName = ((CacheStringReturnValue)(mtdSignature.ReturnValue)).Value;
Copy code to clipboard

Example: Accessing Sample.Person

This section provides sample code that uses the dynamic interface to access a Sample.Person object.

GetMtdSignature()

The following code creates the CacheObject and CacheMethodSignature objects used by these examples:

   CacheObject person = new CacheObject(conn, "Sample.Person");
   CacheMethodSignature mtdSignature = conn.GetMtdSignature();
Copy code to clipboard
Add(), SetProperty()

The following code sets the Person.Name property to the value of valueOfName:

   string valueOfName = "test";
   mtdSignature.Add(valueOfName, false);
   person.SetProperty("Name", mtdSignature);
Copy code to clipboard
Clear(), SetReturnType(), GetProperty()

Now the method signature is cleared, the return type is set, and the new value of the Person.Name property is retrieved:

   mtdSignature.Clear();
   mtdSignature.SetReturnType(conn, ClientTypeId.tString);
   person.GetProperty("Name", mtdSignature);
   string returnedNameValue = ((CacheStringReturnValue)(mtdSignature.ReturnValue)).Value;
Copy code to clipboard

The .NET TestTools.UnitTesting.Assert class is used to compare the property value to the value in the original variable.

   Assert.AreEqual(valueOfName, returnedNameValue);
Copy code to clipboard
Accessing an object property

The following code gets the Person.Home object property, tests the object to see if it is connected, then closes the Person object and tests to see if the Person.Home object has been disconnected.

   mtdSignature.Clear();
   mtdSignature.SetReturnType(conn, ClientTypeId.tObject);
   person.GetProperty("Home", mtdSignature);
   ICacheObject home = ((CacheObjReturnValue)(mtdSignature.ReturnValue)).Value;

   Assert.IsTrue(home.IsConnected);
   person.Close();
   Assert.IsFalse(home.IsConnected);
Copy code to clipboard
RunClassMethod()

This example calls the StoredProcTest() class method, which is declared as follows in the Sample.Person server class:

   classmethod StoredProcTest(name As %String, ByRef response As %String) as %Integer
Copy code to clipboard

StoredProcTest() concatenates two copies of name and returns the resulting string in response. It always sets the return value of the method to 29.

The following code sets the signature values and return type for the method:

   string nameValue = "test";
   string responseValue = "";

   mtdSignature.Clear();
   mtdSignature.Add(nameValue, false);
   mtdSignature.Add(responseValue, true);
   mtdSignature.SetReturnType(conn, ClientTypeId.tInt);
Copy code to clipboard

Now the method is called, and the results are retrieved and tested:

   CacheObject.RunClassMethod(conn, "Sample.Person", "StoredProcTest", mtdSignature)

   responseValue = ((CacheStringArgument)(mtdSignature.Arguments[1])).Value;
   string expectedValue = nameValue + "||" + nameValue;
   Assert.AreEqual(responseValue, expectedValue);

   long? returnValue = ((CacheIntReturnValue)(mtdSignature.ReturnValue)).Value;
   Assert.AreEqual(returnValue, 29);
Copy code to clipboard

CacheMethodSignature Methods and Properties

This section provides a quick overview of the CacheMethodSignature class. It is not intended to be your primary reference for the class, and therefore omits some items (such as methods inherited from System.Object) that are not used in this chapter.

Note:

For the most complete and up to date information on this class and related enumerations, refer to the entry in the Caché .NET Help File.

The CacheMethodSignature class provides the following methods and properties:

  • Add() — Specifies an argument value to be added to the method signature.

  • Arguments — Field containing an array of method argument values.

  • Clear() — Initializes this instance by deleting any previously specified argument values and method return settings.

  • Get() — Gets the value of the argument at the specified index.

  • ReturnValue — Field containing the method return value.

  • SetColnReturnType() — Sets the method return type if a collection is to be returned.

  • SetReturnType() — Sets the method return type.

The following related enumerations are also listed here:

Add()

Adds the specified argument value to the method signature. This method has the following overloads:

public void Add(Object arg, CacheConnection conn, Type argType, ClientTypeId typeId, bool byRef)

public void Add(ICacheObject arg, CacheConnection conn, Type argType, bool byRef)

public void Add(CacheStatus arg, CacheConnection conn, bool byRef)
public void Add(CacheSysList arg, CacheConnection conn, bool byRef)

public void Add(CacheDate arg, int typeId, bool byRef)

public void Add(Nullable<(long> arg, bool byRef)
public void Add(Nullable<double> arg, bool byRef)
public void Add(Nullable<DateTime> arg, bool byRef)
public void Add(Nullable<bool> arg, bool byRef)
public void Add(Nullable<decimal> arg, bool byRef)
public void Add(byte[] arg, bool byRef)
public void Add(string arg, bool byRef)
public void Add(CacheTime arg, bool byRef)
Copy code to clipboard
  • arg (various data types) — An argument value.

  • conn (CacheConnection) — The connection object.

  • argType (Type) — The argument type.

  • typeId (ClientTypeId) — if arg is an object, specifies the object type as a constant from the ClientTypeId enumeration.

  • byRef (Boolean) — If set to true, the argument is passed by reference.

Arguments

Field containing an array of currently defined method arguments.

public ArrayList Arguments
Copy code to clipboard
Clear()

Initializes this instance by deleting any previously specified argument values and method return settings.

public void Clear()
Copy code to clipboard
Get()

Gets the argument at the specified index. This method has the following overloads:

public void Get(int idx, out ICacheObject arg)
public void Get(int idx, out Nullable<long> arg)
public void Get(int idx, out Nullable<double> arg)
public void Get(int idx, out Byte[] arg)
public void Get(int idx, out String arg)
public void Get(int idx, out CacheStatus arg)
public void Get(int idx, out CacheTime arg)
public void Get(int idx, out CacheDate arg)
public void Get(int idx, out Nullable<DateTime> arg)
public void Get(int idx, out Nullable<bool> arg)
public void Get(int idx, out Nullable<decimal> arg)
public void Get(int idx, out CacheSysList arg)
Copy code to clipboard
  • idx (Int32) — The index specifying which argument to return.

  • arg (various data types) — The argument to be returned.

ReturnValue

Field containing a Server method return value.

public CacheReturnValue ReturnValue
Copy code to clipboard
SetColnReturnType()

Sets the method return type if a collection is to be returned.

public void SetColnReturnType(CacheConnection conn, ClientObjTypeId objTypeId, ClientTypeId colnTypeId)
Copy code to clipboard
SetReturnType()

Sets the method return type. This method has the following overloads:

public void SetReturnType(CacheConnection conn, int typeId)
public void SetReturnType(CacheConnection conn, ClientTypeId typeId)
public void SetReturnType(CacheConnection conn, Type clientType)
public void SetReturnType(CacheConnection conn, int objTypeId , int colnTypeId )
Copy code to clipboard
  • conn (CacheConnection) — The connection object.

  • typeId (Int32 or ClientTypeId) — The type of the return value, specified as either an integer or a constant from the ClientTypeId enumeration.

  • clientType (System.Type) — The type of the return value, specified as a type declaration.

  • objTypeId (Int32) — If the return value is a collection, specifies the data type id for the collection elements (see the ClientTypeId enumeration).

  • colnTypeId (Int32) — If the return value is a collection, specifies the collection type (see the ClientObjTypeId enumeration).

ClientTypeId Enumeration

The InterSystems.Data.CacheTypes.ClientTypeId enumeration includes the following values:

   tVoid = -1
   tObject = 0
   tInt = 1
   tDouble = 2
   tBinary = 3
   tString = 4
   tStatus = 5
   tTime = 6
   tDate = 7
   tTimeStamp = 8
   tBool = 9
   tCurrency = 10
   tList = 11
   tLongString = 12
   tLongBinary = 13
   tDecimal = 14
   tMVDate = 15
Copy code to clipboard
ClientObjTypeId Enumeration

The InterSystems.Data.CacheTypes.ClientObjTypeId enumeration includes the following values:

   tUnknown = 0
   tListOfDT = 1
   tArrayOfDT = 2
   tListOfObj = 3
   tArrayOfObj = 4
   tRelationship = 5
   tBinStream = 6
   tCharStream = 7
Copy code to clipboard