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 Native API, Object Gateway proxy objects, and ObjectScript applications can all share the same connection and work together in the same context.
The Native API allows you to create instances of ObjectScript classes on InterSystems IRIS and generate Object Gateway proxy objects for them at runtime. Your .NET application can use proxies to work with ObjectScript objects as easily as if they were native .NET objects.
You can write custom ObjectScript classmethods or functions for any purpose, and your application can use the Native API to call them just as easily as native .NET methods.
The Native API provides direct access to the high performance native data structures (global arrays) that underpin the InterSystems IRIS multidimensional storage model. Global arrays can be created, read, changed, and deleted in .NET applications just as they can in ObjectScript.
The following brief examples demonstrate how easy it is to add all of these abilities to your .NET application.
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);
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.
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);
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.
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");
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.
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");