Introduction to the Native API

Introduction to Global ArraysCopy link to this section

A global array, like all sparse arrays, is a tree structure rather than a sequentially numbered list. The basic concept behind global arrays can be illustrated by analogy to a file structure. Each directory in the tree is uniquely identified by a path composed of a root directory identifier followed by a series of subdirectory identifiers, and any directory may or may not contain data.

Global arrays work the same way: each node in the tree is uniquely identified by a node address composed of a global name identifier and a series of subscript identifiers, and a node may or may not contain a value. For example, here is a global array consisting of five nodes, two of which contain values:

   root -->|--> foo --> SubFoo='A'
           |--> bar --> lowbar --> UnderBar=123

Copy code to clipboard

Values could be stored in the other possible node addresses (for example, root or root->bar), but no resources are wasted if those node addresses are valueless. In InterSystems ObjectScript globals notation, the two nodes with values would be:

   root('foo','SubFoo')
   root('bar','lowbar','UnderBar')

Copy code to clipboard

The global name (root) is followed by a comma-delimited subscript list in parentheses. Together, they specify the entire path to the node.

This global array could be created by two calls to the Native API set() method:

  native.set('A', 'root', 'foo', 'SubFoo');
  native.set(123, 'root', 'bar', 'lowbar', 'UnderBar');

Copy code to clipboard

Global array root is created when the first call assigns value 'A' to node root('foo','SubFoo'). Nodes can be created in any order, and with any set of subscripts. The same global array would be created if we reversed the order of these two calls. The valueless nodes are created automatically, and will be deleted automatically when no longer needed. For details, see “Creating, Updating, and Deleting Nodes” in the next chapter).

The Native API code to create this array is demonstrated in the following example. A Connection object connects to the server and an instance of class Iris is created. Iris methods are used to create a global array, read the resulting persistent values from the database, and then delete the global array.

// Create a reference to the Native API module
  const IRISNative = require('intersystems-iris-native')

// Open a connection to the server and create an Iris object
  let connectionInfo = {
    host: '127.0.0.1',
    port: 51773,
    ns: 'USER',
    user: '_SYSTEM',
    pwd: 'SYS'
  };
  const conn = IRISNative.createConnection(connectionInfo);
  const native = conn.createIris();

// Create a global array in the USER namespace on the server
  native.set('A', 'root', 'foo', 'SubFoo');
  native.set(123, 'root', 'bar', 'lowbar', 'UnderBar');

// Read the values from the database and print them
  let subfoo = native.get('root', 'foo', 'SubFoo')
  let underbar = native.get('root', 'bar', 'lowbar', 'UnderBar')
  console.log('Created two values: ');
  console.log('   root("foo","SubFoo")=' + subfoo);
  console.log('   root("bar","lowbar","UnderBar")=' + underbar);

Copy code to clipboard

NativeDemo prints the following lines:

  Created two values:
     root("foo","SubFoo")=A
     root("bar","lowbar","UnderBar")=123

Copy code to clipboard

In this example, IRISNative is an instance of the Native API. Static method createConnection() defines a Connection object named conn that provides a connection to the database associated with the USER namespace. Native API methods perform the following actions:

• Connection.createIRIS() creates a new instance of Iris named native, which will access the database through server connection conn.

• Iris.set() creates new persistent nodes in database namespace USER.

• Iris.get() queries the database and returns the values of the specified nodes.

• Iris.kill() deletes the specified root node and all of its subnodes from the database.

The next chapter provides detailed explanations and examples for all of these methods.

Glossary of Native API TermsCopy link to this section

See the previous section for an overview of the concepts listed here. Examples in this glossary will refer to the global array structure listed below. The Legs global array has ten nodes and three node levels. Seven of the ten nodes contain values:

  Legs                       // root node, valueless, 3 child nodes
    fish = 0                 // level 1 node, value=0
    mammal                   // level 1 node, valueless
      human = 2              // level 2 node, value=2
      dog = 4                // level 2 node, value=4
    bug                      // level 1 node, valueless, 3 child nodes
      insect = 6             // level 2 node, value=6
      spider = 8             // level 2 node, value=8
      millipede = Diplopoda  // level 2 node, value='Diplopoda', 1 child node
        centipede = 100      // level 3 node, value=100

Copy code to clipboard

Naming rules