Skip to main content
Previous sectionNext section

Introduction to the Native API

The Native API for .NET is a lightweight interface to powerful InterSystems IRIS® resources that were once available only through ObjectScript. With the Native API, your applications can take advantage of seamless InterSystems IRIS data platform integration:

The following brief examples demonstrate how easy it is to add all of these abilities to your .NET application.

Implement transparent bidirectional communication between ObjectScript and .NET

The Native API for .NET is implemented as an extension to the InterSystems ADO.NET Managed Provider. Connections are created just they would be for any other application using the Managed Provider (see Using the InterSystems Managed Provider for .NET). This example opens a connection and then creates an instance of the Native API IRIS class:

//Open a connection to InterSystems IRIS
  IRISConnection conn = new IRISConnection();
  conn.ConnectionString = "Server = localhost; " + "Port = 1972; "
    + "Namespace = USER; " + "Password = SYS; " + "User ID = _SYSTEM;";
  conn.Open();

// Use the connection to create an instance of the Native API
  IRIS iris = IRIS.CreateIRIS(conn);
Copy code to clipboard

This connection can also be used by the InterSystems Object Gateway, allowing your .NET and ObjectScript applications to share the same context and work with the same objects.

Create and use individual instances of an ObjectScript class

Your application can create an instance of an ObjectScript class, immediately generate an Object Gateway proxy for it, and use the proxy to work with the ObjectScript instance (see the chapter on “Using .NET Reverse Proxy Objects”).

In this example, the first line calls the %New() method of ObjectScript class Demo.dataStore, creating an instance in InterSystems IRIS. In .NET, the call returns a corresponding proxy object named dataStoreProxy, which is used to call instance methods and get or set properties of the ObjectScript instance:

// use a classmethod call to create an ObjectScript instance and generate a proxy object
  IRISObject dataStoreProxy = (IRISObject)iris.ClassMethodObject("Demo.dataStore","%New");

// use the proxy to call instance methods, get and set properties
  dataStoreProxy.InvokeVoid("ititialize");
  dataStoreProxy.Set("propertyOne","a string property");
  String testString = dataStoreProxy.Get("propertyOne");
  dataStoreProxy.Invoke("updateLog","PropertyOne value changed to "+testString);

// pass the proxy back to ObjectScript method ReadDataStore()
  iris.ClassMethodObject("Demo.useData","ReadDataStore",dataStoreProxy);
Copy code to clipboard

The last line of this example passes the dataStoreProxy proxy to an ObjectScript method named ReadDataStore(), which interprets it as a reference to the original ObjectScript instance. From there, the instance could be saved to the database, passed to another ObjectScript application, or even passed back to your .NET application.

Call ObjectScript classmethods and user-defined functions

You can easily call an ObjectScript classmethod or function (see the chapter on “Calling ObjectScript Methods and Functions”).

  String currentNameSpace = iris.ClassMethodString("%SYSTEM.SYS","NameSpace");
Copy code to clipboard

This example just calls a classmethod to get some system information, but the real power of these calls is their ability to leverage user-written code. You can write custom ObjectScript classmethods or functions for any purpose, and your .NET application can call them as easily as it calls native .NET methods.

Work with multidimensional global arrays

The Native API provides all the methods needed to manipulate global arrays (see the chapter on “Working with Global Arrays”). You can easily access and manipulate globals, traverse multilevel global arrays, and inspect data structures just as you can in ObjectScript. The following example demonstrates how to create, read, change, and delete a simple global array.

// Create a global (ObjectScript equivalent: set ^myGlobal("subOne") = 10)
  iris.Set(10, "myGlobal", "subOne");

// Change, read, and delete the global
  iris.increment(2, "myGlobal", "subOne")   // increment value to 12
  Console.Write("New number is " + iris.GetInteger("myGlobal", "subOne"));
  iris.Kill("myGlobal", "subOne");
Copy code to clipboard