Accessing Global Arrays with Node.js

Glossary of Global Array Terms

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

Global Naming Rules

Global names and subscripts obey the following rules:

• The length of a node address (totaling the length of the global name and all subscripts) can be up to 511 characters. (Some typed characters may count as more than one encoded character for this limit. For more information, see “Maximum Length of a Global Reference” in Using Globals).

• A global name can include letters, numbers, and periods ('.'), and can have a length of up to 31 significant characters. It must begin with a letter, and must not end with a period.

• A subscript can be a string, an integer, or a number. String subscripts are case-sensitive, and can contain any character (including non-printing characters). Subscript length is restricted only by the maximum length of a node address.

Iterating Over a Set of Child Nodes

Child nodes are sets of nodes immediately under the same parent node. Any child node address can be defined by appending one subscript to the subscript list of the parent. For example, the following global array has four child nodes under parent node heroes('dogs'):

The heroes global array

This global array uses the names of several heroic dogs (plus a reckless boy and a pioneering sheep) as subscripts. The values are birth years.

heroes                               // root node, no value, 2 child nodes
  heroes('dogs')                            // level 1, no value, 4 child nodes
    heroes('dogs','Balto') = 1919              // level 2, value=1919
    heroes('dogs','Hachiko') = 1923            // level 2, value=1923
    heroes('dogs','Lassie') = 1940             // level 2, value=1940, 1 child
      heroes('dogs','Lassie','Timmy') = 1954      // level 3, value=1954
    heroes('dogs','Whitefang') = 1906          // level 2, value=1906
  heroes('sheep')                           // level 1, no value, 1 child
    heroes('sheep','Dolly') = 1996             // level 2, value=1996

The following methods are used to create an iterator, define the direction of iteration, and set the starting point of the search:

• Iris.iterator() returns an instance of Iterator for the child nodes of the specified target node.

• Iterator.reversed() — toggles direction of iteration between forward and reverse collation order.

• Iterator.startFrom() sets the iterator's starting position to the specified subscript. The subscript is an arbitrary starting point, and does not have to address an existing node.

Read child node values in reverse order

The following code iterates over child nodes of heroes('dogs') in reverse collation order, starting with subscript V:

// Iterate in reverse, seeking nodes lower than heroes('dogs','V') in collation order
  let iterDogs = irisjs.iterator('heroes','dogs').reversed().startFrom('V');

  let output = '\nDog birth years: ';
  for ([key,value] of iterDogs) {
    output += key + ':' + value + '  ';
  };
  console.log(output);

This code prints the following output:

  Dog birth years: Lassie:1940  Hachiko:1923  Balto:1919

In this example, two subnodes of heroes('dogs') are ignored:

• Child node heroes('dogs','Whitefang') will not be found because it is outside of the search range (Whitefang is higher than V in collation order).

• Level 3 node heroes('dogs','Lassie','Timmy') will not be found because it is a child of Lassie, not dogs.

See the last section in this chapter (“Testing for Child Nodes and Node Values”) for a discussion of how to iterate over multiple node levels.

Iteration with next()

The Native SDK also supports the standard next() and return type iterator methods:

• Iterator.next() — positions the iterator at the next child node (if one exists) and returns an array containing properties done and value. The done property will be false if there are no more nodes. When an iterator is created, it defaults to the entries() return type.

• Iterator.entries() — sets return type to an array containing both the key (the top level subscript of the child node) and the node value. For example, the returned value for node heroes(,'dogs','Balto') would be ['Balto',1919].

• Iterator.keys() — sets return type to return only the key (the top level subscript).

• Iterator.values() — sets return type to return only the node value.

In the following example, each call to the next() method sets variable iter to an array containing the current values for the iterator done and value properties. Since the keys() method was called when the iterator was created, the value property will contain only the key (top level subscript) for the current child node of heroes('dogs').

Use next() to list the subscripts under node heroes('dogs')

// Get a list of child subscripts under node heroes('dogs')
  let iterDogs = irisjs.iterator('heroes','dogs').keys();
  let output = "\nSubscripts under node heroes('dogs'): ";

  let iter = iterDogs.next();
  while (!iter.done) {
    output += iter.value + ' ';
    iter = iterDogs.next();
  }
  console.log(output);

This code prints the following output:

  Subscripts under node heroes('dogs'): Balto Hachiko Lassie Whitefang

Testing for Child Nodes and Node Values

In the previous examples, the scope of the search is restricted to child nodes of heroes('dogs'). The iterator fails to find two values in global array heroes because they are under different parents:

• Level 3 node heroes('dogs','Lassie','Timmy') will not be found because it is a child of Lassie, not dogs.

• Level 2 node heroes('sheep','Dolly') is not found because it is a child of sheep, not dogs.

To search the entire global array, we need to find all of the nodes that have child nodes, and create an iterator for each set of child nodes. The isDefined() method provides the necessary information:

• Iris.isDefined() — can be used to determine if a node has a value, a subnode, or both. It returns one of the following values:

  • 0 — the specified node does not exist

  • 1 — the node exists and has a value

  • 10 — the node is valueless but has a child node

  • 11 — the node has both a value and a child node

  The returned value can be used to determine several useful boolean values:

     let exists = (irisjs.isDefined(root,subscripts) > 0);      // returns 1, 10, or 11
     let hasValue = (irisjs.isDefined(root,subscripts)%10 > 0); // returns 1 or 11
     let hasChild = (irisjs.isDefined(root,subscripts) > 9);    // returns 10 or 11
  
  

  

The following example consists of two methods:

• findAllHeroes() iterates over child nodes of the current node, and calls testNode() for each node. Whenever testNode() indicates that the current node has child nodes, findAllHeroes() creates a new iterator for the next level of child nodes.

• testNode() will be called for each node in the heroes global array. It calls isDefined() on the current node, and returns a boolean value indicating whether the node has child nodes. It also prints node information for each node.

Method findAllHeroes()

This example processes a known structure, and traverses the various levels with simple nested calls. In the less common case where a structure has an arbitrary number of levels, a recursive algorithm could be used.

  function findAllHeroes() {
    const root = 'heroes';
    console.log('List all subnodes of root node '+root+':\n'+root)
    let iterRoot = irisjs.iterator(root);
    let hasChild = false;

    // Iterate over children of root node heroes
    for ([sub1,value] of iterRoot) {
      hasChild = testNode(value,root,sub1);

      // Iterate over children of heroes(sub1)
      if (hasChild) {
        let iterOne = irisjs.iterator(root,sub1);
        for ([sub2,value] of iterOne) {
          hasChild = testNode(value,root,sub1,sub2);

          // Iterate over children of heroes(sub1,sub2)
          if (hasChild) {
            let iterTwo = irisjs.iterator(root,sub1,sub2);
            for ([sub3,value] of iterTwo) {
              testNode(value,root,sub1,sub2,sub3); //no child nodes below level 3
            }
          } //end level 2
        }
      } //end level 1
    } // end main loop
  } // end findAllHeroes()

Method testNode()

  function testNode(value, root, ...subs) {

  // Test for values and child nodes
    let state = irisjs.isDefined(root,...subs);
    let hasValue = (state%10 > 0); // has value if state is 1 or 11
    let hasChild = (state > 9);    // has child if state is 10 or 11

  // format the node address output string
    let subList = Array.from(subs);
    let level = subList.length-1;
    let indent = '  ' + String('      ').slice(0,(level*2));
    let address = indent + root+'(' + subList.join() + ')';

  // Add node value to string and note special cases
    if (hasValue) { // ignore valueless nodes
      address += ' = ' + value;
      for (name of ['Timmy','Dolly']) {
        if (name == subList[level]) {
          address += ' (not a dog!)'
        }
      }
    }
    console.log(address);
    return hasChild;
  }
}

This method will write the following lines:

List all subnodes of root node heroes:
heroes
  heroes(dogs)
    heroes(dogs,Balto) = 1919
    heroes(dogs,Hachiko) = 1923
    heroes(dogs,Lassie) = 1940
      heroes(dogs,Lassie,Timmy) = 1954  (not a dog!)
    heroes(dogs,Whitefang) = 1906
  heroes(sheep)
    heroes(sheep,Dolly) = 1996  (not a dog!)

The output of testNodes() includes some nodes that were not found in previous examples because they are not child nodes of heroes('dogs'):

• heroes('dogs','Lassie','Timmy') is a child of Lassie, not dogs.

• heroes('sheep','Dolly') is a child of sheep, not dogs.