Skip to main content

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"

Save a Global Node: set()

Synchronous:

   var result = mydata.set(node);

Asynchronous:

   mydata.set(node, function(error, result){});
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 
         }
      }
   );

result:

   Operation successful if no error reported.

Retrieve a Global Node: get()

Synchronous:

   var result = mydata.get(node);

Asynchronous:

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

result:

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

result:

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

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);

Asynchronous:

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

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);

Asynchronous:

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

result:

   {defined: 11}

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);

Asynchronous:

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

result:

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

result:

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

result:

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

result:

   {global: "Customer", subscripts: [1], result: "1"}}
   {global: "Customer", subscripts: [2], result: "2"}}
   {global: "Customer", subscripts: [3], result: "3"}}

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);

Asynchronous:

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

result:

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

result:

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

result:

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

result:

   {global: "Customer", subscripts: [3], result: "3"}}
   {global: "Customer", subscripts: [2], result: "2"}}
   {global: "Customer", subscripts: [1], result: "1"}}

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);

Asynchronous:

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

result:

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

result:

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

result:

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

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
   }

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);

Asynchronous:

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

result:

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

result:

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

result:

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

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
   }

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);

Asynchronous:

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

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})
Example 3 (Increment ^Counter(1) by two)
   result = mydata.increment({global: "Counter", subscripts: [1], increment: 2})

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}};
   );

Asynchronous:

   mydata.merge(
      {{ to: {destination_node},
         from: {source_node}},
      function(error, result){}
   );
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 
         }
      }
   );

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 
         }
      }
   );

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);

Asynchronous:

   mydata.global_directory (range, function(error, result){});
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 
         }
      }
   );

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 
         }
      }
   );

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);

Asynchronous:

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

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){});

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

FeedbackOpens in a new tab