docs.intersystems.com
Home

First Look: InterSystems IRIS Native API for .NET
InterSystems: The power behind what matters   
Search:  


This First Look guide explains how to access InterSystems IRIS globals from a .NET application using the InterSystems IRIS™ Native functionality. IRIS Native also allows you to run ObjectScript methods, functions, and routines. In this exploration, you will first connect to InterSystems IRIS. You will then set and retrieve the value of a global node in InterSystems IRIS and iterate over the nodes of another global. You will also call an InterSystems IRIS class method. All of these activities will be performed from a .NET application.
To give you a taste of IRIS Native without bogging you down in details, this exploration is intentionally simple. These activities are designed to only use the default settings and features, so that you can acquaint yourself with the fundamentals of the feature without having to deal with details that are off-topic or overly complicated. When you bring IRIS Native to your production systems, there may be things you will need to do differently. Be sure not to confuse this exploration of IRIS Native with the real thing!
To browse all of the First Looks, including others that can be performed on a free cloud instance or web instance, see InterSystems First Looks.
Introduction to InterSystems IRIS Storage Structures
InterSystems IRIS provides an easy-to-use way to store data in persistent, multidimensional arrays. A global is a named multidimensional array that is stored within a physical InterSystems IRIS database. Within an application, the mappings of globals to physical databases is based on the current namespace — a namespace provides a logical, unified view of one or more physical databases. As an example, by entering the code below into the InterSystems IRIS Terminal (see Connecting to an InterSystems IRIS Instance in the chapter “Using Multiple Instances of InterSystems IRIS” in the System Administration Guide), you can associate the value “Red” with the key “Color” using a global named ^Settings:
 set ^Settings("Color")="Red"
You can take advantage of the multidimensional nature of globals to define a more complex structure:
 set ^Settings("Auto1","Properties","Color") = "Red"
 set ^Settings("Auto1","Properties","Model") = "SUV"
 set ^Settings("Auto2","Owner") = "Mo"
 set ^Settings("Auto2","Properties","Color") = "Green"
For more information on globals, see Using Globals.
Exploring IRIS Native for .NET
At this point, you are ready to experiment with IRIS Native. The following brief demo shows you how to work with IRIS Native in a .NET application.
Before You Begin
To run this demo you’ll need a machine with a running instance of InterSystems IRIS, the .NET framework, and Visual Studio.
To use the procedure, you’ll need an instance of InterSystems IRIS and a system with the .NET framework and Visual Studio. Select the InterSystems IRIS instance in one of these ways:
You can configure Visual Studio to connect to your InterSystems IRIS instance whether it is local, on the network, in the cloud, or on the web. For instructions, see InterSystems IRIS Connection Information and .Net IDEs in InterSystems IRIS Basics: Connecting an IDE.
Configuring the Visual Studio Project
To begin, open Visual Studio and create a new console app project, selecting the Visual C# and Console App (.NET Framework) options. For the Name field, enter netnative.
Adding the Assembly Reference
The InterSystems.Data.IRISClient.dll assembly must be installed on your local system. You can download it from https://github.com/intersystems/quickstarts-dotnet/tree/master/EFPlay/bin/Debug or using the link in the Connecting Your .NET Application section of the InterSystems Labs page. If InterSystems IRIS is installed on your local system, the assembly is already installed in the subdirectory install-dir\dev\dotnet\bin\v4.5, where install-dir is the installation directory for your instance of InterSystems IRIS.
To add an assembly reference to InterSystems.Data.IRISClient.dll to a project:
  1. From the Visual Studio main menu, select Project > Add Reference...
  2. In the resulting window, click Browse....
  3. Browse to the location of the InterSystems.Data.IRISClient.dll file.
  4. Select the file and click Add.
  5. Click OK.
In the Visual Studio Solution Explorer, the InterSystems.Data.IRISClient.dll assembly should now be listed under References.
Using IRIS Native
At this point, you are ready to experiment with IRIS Native. Open the file that was created when you created the Visual Studio project (for example, Program.cs). Delete the default content of the file and paste in the following code, substituting the connection information for your InterSystems IRIS instance (as described in InterSystems IRIS Connection Information in InterSystems IRIS Basics: Connecting an IDE) for the values in conn.ConnectionString. (The value oflogfile must be a writable path on the local system). You can specify the USER namespace as shown, or you can choose another that you have created in your installed instance.
using System;
using InterSystems.Data.IRISClient;
using InterSystems.Data.IRISClient.ADO;

public class IRISNative
{
   
    public static void Main(String[] args)
    {
        try
        {
            // open connection to InterSystems IRIS instance using connection string
            IRISConnection conn = new IRISConnection();
            
            // edit this ConnectionString to match your environment
            conn.ConnectionString = "Server=localhost; Port=51773; Namespace=User; Password=SYS; User ID=_system; \
              logfile=c:\\sandbox\\dbnative.log";
            conn.Open();
            
            
            // create IRIS Native object
            IRIS iris = IRIS.CreateIRIS(conn);

            Console.WriteLine("[1. Setting and getting a global]");
            
            // setting and getting a global
            // ObjectScript equivalent: set ^testglobal("1") = 8888
            iris.Set(8888, "^testglobal", "1");

            // ObjectScript equivalent: set globalValue = $get(^testglobal("1"))
            Int16? globalValue = iris.GetInt16("^testglobal", "1");

            Console.WriteLine("The value of ^testglobal(1) is " + globalValue);
            Console.WriteLine();

            
            Console.WriteLine("[2. Iterating over a global]");

            // modify global to iterate over
            // ObjectScript equivalent: set ^testglobal("1") = 8888
            // ObjectScript equivalent: set ^testglobal("2") = 9999
            iris.Set(8888, "^testglobal", "1");
            iris.Set(9999, "^testglobal", "2");

            // iterate over all nodes forwards
            Console.WriteLine("walk forwards");
            IRISIterator subscriptIter = iris.GetIRISIterator("^testglobal");
            foreach (var node in subscriptIter)
            {
                Console.WriteLine("subscript=" + subscriptIter.CurrentSubscript + ", value=" + node);
            }
            Console.WriteLine();
            

            Console.WriteLine("[3. Calling a class method]");

            // calling a class method
            // ObjectScript equivalent: set returnValue = ##class(%Library.Utility).Date(5)
            String returnValue = iris.ClassMethodString("%Library.Utility", "Date", 5);
            Console.WriteLine(returnValue);

            Console.WriteLine();

            // close IRIS object and connection
            iris.Close();
            conn.Close();
            
        }
        catch (Exception ex)
        {
            Console.WriteLine(ex.Message);
        }
    }

}
The example code is split into three sections:
  1. The first section shows how you set the value of a global and later retrieve it. The commands executed in this section are equivalent to the ObjectScript commands SET and GET.
  2. The second section shows how to iterate through the subnodes of a global, similar to the $ORDER ObjectScript function.
  3. The third section shows how you call an ObjectScript class method from your .NET application using IRIS Native.
If you are using a locally installed instance and the connection therefore uses localhost as the server address, the program will use a local shared memory connection, which is even faster than the standard TCP/IP connection.
Note:
Globals in ObjectScript begin with the caret character ( ^ ). This is not a requirement in your .NET applications that use the InterSystems IRIS Native API.
Running the Exercise
You are now ready to run the demo application by pressing Ctrl+F5. If the example executes successfully, you should see printed output with the results of the sample code:
[1. Setting and getting a global]
The value of ^testglobal(1) is 8888

[2. Iterating over a global]
walk forwards
subscript=1, value=8888
subscript=2, value=9999

[3. Calling a class method]
Oct 30, 2018
Confirming the Changes in the Management Portal
Next, confirm your results in the Management Portal, using the following procedure.
  1. Open the Management Portal for your instance in your browser. The URL to use depends on the type of instance you selected; for information about determining the correct URL, see InterSystems IRIS Connection Information in InterSystems IRIS Basics: Connecting an IDE.
  2. If you are not in the namespace you specified in the code, switch to it.
  3. Navigate to the Globals page (System Explorer > Globals). You should see the testglobal global created in the example code. Click View to see its contents. You should see the two nodes of the global: ^testglobal(1) = 8888 and ^testglobal(2) = 9999.
Learn More About IRIS Native
For more information on IRIS Native, globals, and InterSystems IRIS, see:
Using the Native API for .NET
First Look: InterSystems IRIS Native API for Java
Using Globals
Using the InterSystems Managed Provider for .NET


View this article as PDF   |  Download all PDFs
Copyright © 1997-2019 InterSystems Corporation, Cambridge, MA
Content Date/Time: 2019-04-23 13:43:20