Skip to main content
Previous sectionNext section

NoSQL Methods for Global Nodes

In the following subsections we will discuss the basic NoSQL-style methods which include the following operations:

Create, read, update, and delete operations

Iteration

Other operations

Note:
Data used in Basic NoSQL examples

In this chapter the examples will be based on the following simple Caché data set:

   ^Customer(1)="Jane K. White"
   ^Customer(1, "address")="Banstead"
   ^Customer(2)="John P.Jackson"
   ^Customer(3)="Jane Smith"
Copy code to clipboard

Save a Global Node: set()

Synchronous:

   var result = mydata.set(node);
Copy code to clipboard

Asynchronous:

   mydata.set(node, function(error, result){});
Copy code to clipboard
Example:
   mydata.set(
      {global: "Customer", subscripts: [1], data: "Jane K. White"},
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
Copy code to clipboard

result:

   Operation successful if no error reported.
Copy code to clipboard

Retrieve a Global Node: get()

Synchronous:

   var result = mydata.get(node);
Copy code to clipboard

Asynchronous:

   mydata.get(node, function(error, result){});
Copy code to clipboard
Example 1 (Synchronous)
   result = mydata.get({global: "Customer", subscripts: [9]});
Copy code to clipboard

result:

   {global: "Customer", subscripts: [9], data: "", defined: 0}
Copy code to clipboard
Example 2 (Asynchronous)
   mydata.get(
      {global: "Customer", subscripts: [1]},
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
Copy code to clipboard

result:

   {global: "Customer", subscripts: [1], data: "Jane K. White", defined: 1}
Copy code to clipboard

Note that the defined property is set to 1 if the global node is actually defined and set to 0 if it is not.

Delete a Global Node: kill()

Synchronous:

   var result = mydata.kill(node);
Copy code to clipboard

Asynchronous:

   mydata.kill(node, function(error, result){});
Copy code to clipboard
Example:
   mydata.kill(
      {global: "Customer", subscripts: [1]},
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
Copy code to clipboard

result:

Operation successful if no error reported.

Test for the Existence of a Global Node: data()

This method will return one of the following numeric values:

  • 0 — Node does not exist.

  • 1 — Node contains data but has no subnodes.

  • 10 — Node does not contain data but has subnodes.

  • 11 — Node contains data and has subnodes.

This method will return one of the following numeric values:

  • 0: Global node is undefined.

  • 1: Global node points to a data value. Global(1)="Data" data(Global(1))

  • 10: Global node does not point to data but is further subscripted. Global(1,1)="Data" data(Global(1))

  • 11: Global node points to a data value and is further subscripted. Global(1)="Data 1", ^Global(1,1)="Data 1" data(Global(1))

Synchronous:

   var result = mydata.data(node);
Copy code to clipboard

Asynchronous:

   mydata.data(node, function(error, result){});
Copy code to clipboard
Example:
   mydata.data(
      {global: "Customer", subscripts: [1]},
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
Copy code to clipboard

result:

   {defined: 11}
Copy code to clipboard

Get the Next Global Subscript: next()

Get the next value in the collating sequence for a particular level of subscript.

Synchronous:

   var result = mydata.order(node);
Copy code to clipboard

Asynchronous:

   mydata.order(node, function(error, result){});
Copy code to clipboard
Example 1 (Synchronous)
   result = mydata.order({global: "Customer", subscripts: [""]},
Copy code to clipboard

result:

   {global: "Customer", subscripts: [1], result: "1"}}
Copy code to clipboard
Example 2 (Synchronous)
   result = mydata.next({global: "Customer", subscripts: [3]},
Copy code to clipboard

result:

   {global: "Customer", subscripts: [""], result: ""}}
Copy code to clipboard
Example 3 (Asynchronous)
   mydata.next(
      {global: "Customer", subscripts: [1]},
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
Copy code to clipboard

result:

   {global: "Customer", subscripts: [2], result: "2"}}
Copy code to clipboard
Example 4 (Parse at the first level)
   key = {global: "Customer", subscripts: [""]};
   while ((key = user.next(key)).result != "") {
      console.log(JSON.stringify(key, null, '\t'))
   }
Copy code to clipboard

result:

   {global: "Customer", subscripts: [1], result: "1"}}
   {global: "Customer", subscripts: [2], result: "2"}}
   {global: "Customer", subscripts: [3], result: "3"}}
Copy code to clipboard

If there is no further subscript defined in the sequence then the result property will be returned as empty string ("").

Get the Previous Global Subscript: previous()

Get the previous value in the collating sequence for a particular level of subscript.

Synchronous:

   var result = mydata.previous(node);
Copy code to clipboard

Asynchronous:

   mydata.previous(node, function(error, result){});
Copy code to clipboard
Example 1 (Synchronous)
   result = mydata.previous({global: "Customer", subscripts: [""]},
Copy code to clipboard

result:

   {global: "Customer", subscripts: [3], result: "3"}}
Copy code to clipboard
Example 2 (Synchronous)
   result = mydata.previous({global: "Customer", subscripts: [2]},
Copy code to clipboard

result:

   {global: "Customer", subscripts: ["1"], result: "1"}}
Copy code to clipboard
Example 3 (Asynchronous)
   mydata.previous(
      {global: "Customer", subscripts: [1]},
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
Copy code to clipboard

result:

   {global: "Customer", subscripts: [""], result: ""}}
Copy code to clipboard
Example 4 (Parse at the first level)
   key = {global: "Customer", subscripts: [""]};
   while ((key = user.previous(key)).result != "") {
      console.log(JSON.stringify(key, null, '\t'))
   }
Copy code to clipboard

result:

   {global: "Customer", subscripts: [3], result: "3"}}
   {global: "Customer", subscripts: [2], result: "2"}}
   {global: "Customer", subscripts: [1], result: "1"}}
Copy code to clipboard

If there is no further subscript defined in the sequence then the result property will be returned as empty string ("").

Get the Next Global Node: next_node()

Get the next whole global node in the collating sequence regardless of the level of subscript.

Synchronous:

   var result = mydata.next_node(node);
Copy code to clipboard

Asynchronous:

   mydata.next_node(node, function(error, result){});
Copy code to clipboard
Example 1 (Synchronous)
   result = mydata.next_node({global: "Customer"},
Copy code to clipboard

result:

   {global: "Customer", subscripts: [1], data: "Jane K. White, defined: 1}}
Copy code to clipboard
Example 2 (Synchronous)
   result = mydata.next_node({global: "Customer", subscripts: [3]},
Copy code to clipboard

result:

   {global: "Customer", defined: 0}}
Copy code to clipboard
Example 3 (Asynchronous)
   mydata.next_node(
      {global: "Customer", subscripts: [1]},
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
Copy code to clipboard

result:

   {
      global: "Customer",
      subscripts: [1, "address"],
      data: "Banstead",
      defined: 1
   }
Copy code to clipboard
Example 4 (Parse global)
   key = {global: "Customer"};
   while ((key = user.next_node(key)).defined) {
      console.log(JSON.stringify(key, null, '\t'));
   }
Copy code to clipboard

key:

   {
      global: "Customer",
      subscripts: [1],
      data: "Jane K. White",
      defined: 1
   }
   {
      global: "Customer",
      subscripts: [1, "address"],
      data: "Banstead",
      defined: 1
   }
   {
      global: "Customer",
      subscripts: [2],
      data: "John P.Jackson",
      defined: 1
   }
   {
      global: "Customer",
      subscripts: [3],
      data: "Jane Smith",
      defined: 1
   }
Copy code to clipboard

If there is no further node defined in the sequence then the defined property will be set to zero.

Get the Previous Global Node: previous_node()

Get the previous whole global node in the collating sequence regardless of the level of subscript.

Synchronous:

   var result = mydata.previous_node(node);
Copy code to clipboard

Asynchronous:

   mydata.previous_node(node, function(error, result){});
Copy code to clipboard
Example 1 (Synchronous)
   result = mydata.previous_node({global: "Customer", subscripts: ["z"]},
Copy code to clipboard

result:

   {global: "Customer", subscripts: [3], data: "Jane Smith", defined: 1}}
Copy code to clipboard
Example 2 (Synchronous)
   result = mydata.previous_node({global: "Customer", subscripts: [2]},
Copy code to clipboard

result:

   {
      global: "Customer",
      subscripts: [1, "address"],
      data: "Banstead",
      defined: 1
   }
Copy code to clipboard
Example 3 (Asynchronous)
   mydata.previous_node(
      {global: "Customer", subscripts: [1]},
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
Copy code to clipboard

result:

   {global: "Customer", defined: 0}}
Copy code to clipboard
Example 4 (Parse global)
   key = {global: "Customer", subscripts: ["z"]};
   while ((key = user.previous_node(key)).defined) {
      console.log(JSON.stringify(key, null, '\t'));
   }
Copy code to clipboard

result:

   {
      global: "Customer",
      subscripts: [3],
      data: "Jane Smith",
      defined: 1
   }
   {
      global: "Customer",
      subscripts: [2],
      data: "John P.Jackson",
      defined: 1
   }
   {
      global: "Customer",
      subscripts: [1, "address"],
      data: "Banstead",
      defined: 1
   }
   {
      global: "Customer",
      subscripts: [1],
      data: "Jane K. White",
      defined: 1
   }
Copy code to clipboard

If there is no further node defined in the sequence then the defined property will be set to zero.

Get the Next Value for an Integer Held in a Global Node: increment()

This method provides an efficient way of uniquely assigning an (incremented) integer to a process without using locking. When called, the integer value held in the global is incremented and the new value returned to the calling program. Caché will guarantee that a unique number is assigned to multiple processes that may be accessing this function simultaneously.

Synchronous:

   var result = mydata.increment(node);
Copy code to clipboard

Asynchronous:

   mydata.increment(node, function(error, result){});
Copy code to clipboard
Example 1 (Increment ^Counter by one)
   mydata.increment(
      {global: "Counter"},
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
Copy code to clipboard

result:

If successful the integer value held in global ^Counter will be incremented and the new value returned as the result.

Example 2 (Increment ^Counter by one – JSON based argument)
   result = mydata.increment({global: "Counter", increment: 1})
Copy code to clipboard
Example 3 (Increment ^Counter(1) by two)
   result = mydata.increment({global: "Counter", subscripts: [1], increment: 2})
Copy code to clipboard

Copy a Global: merge()

The merge() method copies either a whole global or a section of a global to another global.

Synchronous:

   var result = mydata.merge(
      {to: {destination_node},
       from: {source_node}};
   );
Copy code to clipboard

Asynchronous:

   mydata.merge(
      {{ to: {destination_node},
         from: {source_node}},
      function(error, result){}
   );
Copy code to clipboard
Example 1: Copy a whole global
   mydata.merge(
      {to: {global: "CopyOfCustomer"},
       from: {global: "Customer"}},
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
Copy code to clipboard

result:

If successful, the whole of global ^Customer will be copied to ^CopyOfCustomer.

Example 2: Copy a section of global
   mydata.merge(
      {to: {global: "Customer", subscripts: [7, "address"]},
       from: {global: "Customer", subscripts: [1, "address"]}},
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
Copy code to clipboard

result:

If successful, the subsection of global contained under "Customer(1,'address')" will be copied to "Customer(7,'address')".

Get a List of Globals in the Directory: global_directory()

This method will obtain a list of globals held in the directory. The number of names returned can be controlled using the range limiting properties lo, hi and max.

Synchronous:

   var result = mydata.global_directory(range);
Copy code to clipboard

Asynchronous:

   mydata.global_directory (range, function(error, result){});
Copy code to clipboard
Example 1: Obtain a list of all globals in the directory
   mydata.global_directory({},
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
Copy code to clipboard

result:

If successful, an array containing all global names found will be returned.

Example 2: Obtain a list of all globals whose name begins with "Cust"
   mydata.global_directory(
      {lo: "Cust", hi: "Cust~"},
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
Copy code to clipboard

result:

If successful, an array containing all global names beginning with Cust will be returned.

Lock and Unlock Global Nodes: lock() and unlock()

The Caché database contains the facility to lock either whole (for example, ^Customer) or subsections of a global (for example, ^Customer(1)) for exclusive use.

Synchronous:

   var result = mydata.lock(node, timeout);
   var result = mydata.unlock(node);
Copy code to clipboard

Asynchronous:

   mydata.lock(node, timeout, function(error, result){});
   mydata.unlock(node, function(error, result){});
Copy code to clipboard
Example:
   mydata.lock(
      {global: "Customer", subscripts: [1]}, 10,
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
Copy code to clipboard

result:

Operation successful if no error reported. The return value will be 1 if the Global was successfully locked, or 0 if the lock request timed out.

Remember to, at some point, unlock all global nodes that your code previously locked in order to avoid deadlock situations. The lock request is placed on a wait queue if the node is already locked by another process, and will wait indefinitely (until the process terminates) if no timeout is specified.

Finally, to release all locks held by your program call the unlock() method with no node argument.

   var result = mydata.unlock();
   mydata.unlock(function(error, result){});
Copy code to clipboard

All locks held by a Node.js process will be released if and when the process terminates.