Native SDK for Node.js Quick Reference

Connection.close() closes the connection if it is open. Does nothing if the connection is already closed.

   close()

Connection.createIris() returns a new instance of Iris that uses this Connection. Throws an exception if the connection is closed.

   createIris() → {"intersystems-iris".Iris}

Connection.isClosed() returns true if the connection was successful, or false otherwise.

   isClosed() → {Boolean}

Connection.isUsingSharedMemory() returns true if the connection is open and using shared memory to connect to the instance of InterSystems IRIS.

   isUsingSharedMemory() → {Boolean}

Connection.toString() returns the properties of the connection as a JSON string, including the host, port, namespace, timeout, and logfile.

   toString() → {String}

Iris.classMethodValue() and Iris.classMethodObject() calls a class method, passing zero or more arguments and returns the value as a type corresponding to the datatype of the ObjectScript return value. See “Calling Class Methods from Node.js” for details and examples.

This method has a corresponding set of typecast methods (listed below).

  classMethodValue(className, methodName, ...args) → {any}

parameters:

• className — fully qualified name of the class to which the called method belongs.

• methodName — name of the class method.

• ...arguments — zero or more method arguments of the following types:

  • boolean

  • Buffer

  • Decimal

  • number

  • BigInt

  • string

  • IRISList

• callback — a callback function with the signature callback(err: Error, returnValue: any).

This method has a corresponding set of typecast methods (listed below). Also see classMethodVoid(), which is used to call methods that do not return a value.

All of the Iris.classMethodValue() typecast methods listed below work exactly like Iris.classMethodValue(), but also cast the return value to a specific type. See “Calling Class Methods from Node.js” for details and examples.

  classMethodBigInt(className, methodName, ...args) → {BigInt}
  classMethodBoolean(className, methodName, ...args) → {Boolean}
  classMethodBytes(className, methodName, ...args) → {Buffer}
  classMethodDecimal(className, methodName, ...args) → {Decimal}
  classMethodIRISList(className, methodName, ...args) → {IRISList}
  classMethodNumber(className, methodName, ...args) → {Number}
  classMethodString(className, methodName, ...args) → {String}

parameters:

• className — fully qualified name of the class to which the method belongs.

• methodName — name of the class method.

• ...arguments — zero or more method arguments of the following types:

  • String

  • Number

  • Decimal

  • BigInt

  • Buffer

  • IRISList

Iris.classMethodVoid() calls an ObjectScript class method with no return value, passing zero or more arguments. See “Calling Class Methods from Node.js” for details and examples.

  classMethodVoid(className, methodName, ...args)

parameters:

• className — fully qualified name of the class to which the called method belongs.

• methodName — name of the class method.

• ...arguments — zero or more method arguments of the following types:

  • String

  • Number

  • Decimal

  • BigInt

  • Buffer

  • IRISList

This method assumes that there will be no return value, but can be used to call any class method. If you use classMethodVoid() to call a method that returns a value, the method will be executed but the return value will be ignored. Also see Iris.classMethodValue().

Iris.function() calls a function in a routine, passing zero or more arguments and returns the value as a type corresponding to the datatype of the ObjectScript return value.

As of InterSystems IRIS 2024.1, you cannot execute routines through the Native API. If you need to use routines, you should use class execution instead.

This method has a corresponding set of typecast methods (listed below).

  function(functionName, routineName, ...args) → {any}

parameters:

• functionName — name of the function.

• routineName — fully qualified name of the routine to which the called function belongs.

• ...arguments — zero or more function arguments of supported types. Number, string, and IRISList return values are projected as literals. All other values are projected as proxy objects.

This method has a corresponding set of typecast methods (listed below). Also see classMethodVoid(), which is used to call methods that do not return a value.

All of the Iris.function() typecast methods listed below work exactly like Iris.function(), but also cast the return value to a specific type. See “Calling Class Methods from Node.js” for details and examples.

  functionBigInt(functionName, routineName, ...args) → {BigInt}
  functionBoolean(functionName, routineName, ...args) → {Boolean}
  functionBytes(functionName, routineName, ...args) → {Buffer}
  functionDecimal(functionName, routineName, ...args) → {Decimal}
  functionIRISList(functionName, routineName, ...args) → {IRISList}
  functionNumber(functionName, routineName, ...args) → {Number}
  functionObject(functionName, routineName, ...args) → {any}
  functionString(functionName, routineName, ...args) → {String}

parameters:

• functionName — name of the function.

• routineName — fully qualified name of the routine to which the called function belongs.

• ...arguments — zero or more function arguments of supported types. Number, string, and IRISList return values are projected as literals. All other values are projected as proxy objects.

Iris.get() returns the value of the global node as a type corresponding to the ObjectScript datatype of the property.

This method has a corresponding set of typecast methods (listed below).

  get(globalName, ...subscripts) → {any}

parameters:

• globalName — global name

• subscripts — zero or more subscripts specifying the target node

All of the Iris.get() typecast methods listed below work exactly like Iris.get(), but also cast the return value to a specific type.

  getBigInt(globalName, ...subscripts) → {BigInt}
  getBoolean(globalName, ...subscripts) → {Boolean}
  getBytes(globalName, ...subscripts) → {Buffer}
  getDecimal(globalName, ...subscripts) → {Decimal}
  getIRISList(globalName, ...subscripts) → {IRISList}
  getList(globalName, ...subscripts) → {IRISList}
  getNumber(globalName, ...subscripts) → {Number}
  getObject(globalName, ...subscripts) → {any}
  getString(globalName, subscripts) → {String}

The getList() method is retained for backward compatibility. It is identical to getIRISList(), which should be preferred.

parameters:

• globalName — global name

• subscripts — zero or more subscripts specifying the target node

Iris.getAPIVersion() returns the version number as a string for the Native SDK.

  getAPIVersion() → {String}

Iris.getServerVersion() returns the version string for the currently connected InterSystems IRIS server.

  getServerVersion() → {String}

Iris.getTLevel() returns the number of nested transactions currently open in the session (1 if the current transaction is not nested, and 0 if there are no transactions open). This is equivalent to fetching the value of the ObjectScript $TLEVEL special variable. See “Processing Transactions in Node.js” for details and examples.

  getTLevel() → {Number}

Iris.increment() increments the global node with the incrementBy argument and returns the new value of the global node. If there is no existing node at the specified address, a new node is created with the specified value. This method uses a very fast, thread-safe atomic operation to change the value of the node, so the node is never locked. See “Processing Transactions in Node.js” for details and examples.

  increment(incrementBy, globalName, ...subscripts) → {Number}

parameters:

• incrementBy — numeric value to which to set this node (null value sets global to 0, decimal value will be truncated to an integer).

• globalName — global name

• subscripts — zero or more subscripts specifying the target node

Common usage for $INCREMENT is to increment a counter before adding a new entry to a database. $INCREMENT provides a way to do this very quickly, avoiding the use of the LOCK command. See “$INCREMENT and Transaction Processing” in the ObjectScript Reference.

Iris.isDefined() returns a value that indicates whether a node has a value, a child node, or both.

  isDefined(globalName, ...subscripts) → {Number}

Returns one of the following integer values:

• 0 if the node does not exist.

• 1 if the node has a value but no child nodes.

• 10 if the node is valueless but has one or more child nodes.

• 11 if the node has a both a value and child nodes.

parameters:

• globalName — global name

• subscripts — zero or more subscripts specifying the target node

Iris.iterator() returns an Iterator object for the specified node (see "Class Iterator").

  iterator(globalName, ...subscripts) → {"intersystems-iris".Iterator}

parameters:

• globalName — global name

• subscripts — zero or more subscripts specifying the target node

Iris.kill() deletes the specified global node and all of its subnodes. If there is no node at the specified address, the command will do nothing. It will not throw an <UNDEFINED> exception.

  kill(globalName, ...subscripts)

parameters:

• globalName — global name

• subscripts — zero or more subscripts specifying the target node

Iris.lock() locks the global. This method performs an incremental lock (you must call the releaseAllLocks() method first if you want to unlock all prior locks). Throws a <TIMEOUT> exception if the timeout value is reached waiting to acquire the lock. See “Concurrency Control with Node.js” for more information.

  lock(lockType, timeout, lockReference, ...subscript) → {Boolean}

parameters:

• lockType — one of the following strings: "S" for shared lock, "E" for escalating lock, "SE" for both, or "" (default) for non-shared and non-escalating.

• timeout — number of seconds to wait to acquire the lock

• lockReference — a string starting with a circumflex (^) followed by the global name (for example, ^myGlobal, not just myGlobal).

  NOTE: Unlike the globalName parameter used by most methods, the lockReference parameter must be prefixed by a circumflex. Only lock() and unlock() use lockReference instead of globalName.

• subscripts — zero or more subscripts specifying the target node

See “LOCK” in the ObjectScript Reference for detailed information on locks.

Iris.nextSubscript() accepts a node address and returns the subscript of the next sibling node in collation order. This method is similar to $ORDER in ObjectScript.

  nextSubscript(reversed,globalName, ...subscript) → {String|null}

parameters:

• reversed — boolean true indicates that nodes should be traversed in reverse collation order.

• globalName — global name

• subscripts — zero or more subscripts specifying the target node

Iris.node() creates an instance of IRISGlobalNode.

  node(globalName, ...subscript) 

parameters:

• globalName — global name

• subscripts — zero or more subscripts specifying the target node

Iris.procedure() invokes a procedure in a routine.

As of InterSystems IRIS 2024.1, you cannot execute routines through the Native API. If you need to use routines, you should use class execution instead.

  procedure(procedureName, routineName, ...argument) 

parameters:

• procedureName — the name of the procedure to invoke.

• routineName — the name of the routine to which the procedure belongs

• arguments — zero or more subscripts specifying the target node

Iris.releaseAllLocks() releases all locks associated with the session. See “Concurrency Control with Node.js” for more information.

  releaseAllLocks() 

Iris.set() assigns value as the current node value. The value must be one of the following types:

• boolean

• Buffer

• Decimal

• number

• BigInt

• string

• IRISList

  set(value, globalName, ...subscript)

parameters:

• value — new value of the global node

• globalName — global name

• subscripts — zero or more subscripts specifying the target node

Iris.tCommit() commits the current transaction. See “Processing Transactions in Node.js” for details and examples.

  tCommit () 

Iris.tRollback() rolls back all open transactions in the session. See “Processing Transactions in Node.js” for details and examples.

  tRollback () 

Iris.tRollbackOne() rolls back the current level transaction only. This is intended for nested transactions, when the caller only wants to roll back one level. If this is a nested transaction, any higher-level transactions will not be rolled back. See “Processing Transactions in Node.js” for details and examples.

  tRollbackOne () 

Iris.tStart() starts or opens a transaction. See “Processing Transactions in Node.js” for details and examples.

  tStart () 

Iris.unlock() decrements the lock count on the specified lock, and unlocks it if the lock count is 0. To remove a shared or escalating lock, you must specify the appropriate lockType used to lock it. See “Concurrency Control with Node.js” for more information.

  unlock(lockType, lockReference, ...subscript)

parameters:

• lockType — A string specifying the characteristics of the lock to unlock. The locktype you specify for unlock() must have the same shared and escalating characteristics of the original call to lock(). For example, if you created a lock with SE, then you must unlock with SE, SED, or SEI.

  You can use any combination (excluding ones that use both D and I, which are mutually exclusive) of non-empty string values to define a lock with multiple characteristics. For example, SE refers to a shared escalating lock and EI refers to an escalating immediate lock:

  • empty string (default) — non-shared, non-escalating, non-deferred, non-immediate

  • S — shared

  • E — escalating

  • D — deferred

  • I — immediate

• lockReference — a string starting with a circumflex (^) followed by the global name (for example, ^myGlobal, not just myGlobal).

  NOTE: Unlike the globalName parameter used by most methods, the lock_reference parameter must be prefixed by a circumflex. Only lock() and unlock() use lockReference instead of globalName.

• subscripts — zero or more subscripts specifying the target node

IRISList.add() appends the specified value to the IRISList.

  add(value) → {IRISList}

parameters:

• value — the value to append.

IRISList.clear() Deletes all elements in the IRISLIST.

  clear() → {IRISList}

IRISList.count() Returns the number of elements in the IRISLIST.

  count() → {Number}

IRISList.equals() Checks if the current list is equal to another list. Two lists are equal if they have the same size and formatting (locale and compression, as specified by locale and compactDouble).

  equals(list) → {Boolean}

parameters:

• list — The list to compare to.

IRISList.get() retrieves a non-list element at the specified position (1-indexed). To retrieve an element that itself is also a list, use getList() instead.

This method has a corresponding set of typecast methods (listed below).

  get(index) → {any|null}

parameters:

• index — the position of the element to retrieve.

All of the IRISList.get() typecast methods listed below work exactly like IRISList.get(), but also cast the return value to a specific type. They return null if the property does not exist.

  getBigInt(index) → {BigInt|null}
  getBoolean(index) → {Boolean|null}
  getBuffer(index) → {Buffer}
  getBytes(index) → {Buffer|null}
  getDecimal(index) → {Decimal|null}
  getNumber(index) → {Number|null}
  getString(index) → {String|null}

parameters:

• index — the position of the element to retrieve.

IRISList.getList() gets the IRISList at the specified position (1-indexed). IRISList.getIRISList() is an alias of this method.

  getList(index) → {IRISList}

parameters:

• index — the position of the element to retrieve.

IRISList.remove() Removes the list element at the specified position (1-indexed).

  remove(index) → {IRISList}

parameters:

• index — the position of the element to remove.

IRISList.set() Sets the list element at the specified position to a new value. If the index is outside the range of the list, the list is automatically expanded and padded with null elements.

  set(index, value) → {IRISList}

parameters:

• index — the position of the element to change.

• value — the new value.

IRISList.size() Returns the size (in bytes) of the IRISList.

  size() → {Number}

IRISList.toString() Returns the IRISList as a string.

  toString() → {String}

IRISObject.close() closes the IRISObject proxy object, disconnecting it from the object in InterSystems IRIS.

  close()

IRISObject.get() fetches a property value of the proxy object. If the property contains an empty string, it returns null.

This method has a corresponding set of typecast methods (listed below).

  get(propertyName) → {any|null}

parameters:

• propertyName — name of the property to be returned.

All of the IRISObject.get() typecast methods listed below work exactly like IRISObject.get(), but also cast the return value to a specific type. They return null if the property does not exist.

  getBigInt(propertyName) → {BigInt|null}
  getBoolean(propertyName) → {Boolean|null}
  getBytes(propertyName) → {Buffer|null}
  getDecimal(propertyName) → {Decimal|null}
  getIRISList(propertyName) → {IRISList|null}
  getNumber(propertyName) → {Number|null}
  getObject(propertyName) → {any|null}
  getString(propertyName) → {String|null}

parameters:

• propertyName — name of the property to be returned.

IRISObject.invoke() invokes an instance method of the object, returning a variable of a type corresponding to the ObjectScript datatype of the property.

This method has a corresponding set of typecast methods (listed below).

  invoke(methodName, ...arguments) → {any}

parameters:

• methodName — name of the instance method to be called.

• ...arguments — zero or more arguments of supported types.

Also see invokeVoid(), which is used to invoke methods that do not return a value.

All of the IRISObject.invoke() typecast methods listed below work exactly like IRISObject.invoke(), but also cast the return value to a specific type.

  invokeBigInt(methodName, ...arguments) → {BigInt|null}
  invokeBoolean(methodName, ...arguments) → {Boolean|null}
  invokeBytes(methodName, ...arguments) → {Buffer|null}
  invokeDecimal(methodName, ...arguments) → {Decimal|null}
  invokeIRISList(methodName, ...arguments) → {IRISList|null}
  invokeNumber(methodName, ...arguments) → {Number|null}
  invokeObject(methodName, ...arguments) → {any|null}
  invokeString(methodName, ...arguments) → {String|null}

parameters:

• methodName — name of the instance method to be called.

• ...arguments — zero or more arguments of supported types.

IRISObject.invokeVoid() invokes an instance method of the object, but does not return a value.

  invokeVoid(methodName, ...arguments)

parameters:

• methodName — name of the instance method to be called.

• ...arguments — zero or more arguments of supported types.

IRISObject.set() sets a property of the IRISObject.

  set (propertyName, propertyValue)

parameters:

• propertyName — name of the property to which value will be assigned.

• propertyValue — new value of the property. This can be any supported type.

IRISReference.getValue() returns the value of the IRISReference instance as the type corresponding to the value's type in the database.

  getValue() → {any}

All of the IRISReference.getValue() typecast methods listed below work exactly like IRISREference.getValue(), but also cast the return value to a specific type.

  getBigInt() → {BigInt|null}
  getBoolean() → {Boolean|null}
  getBytes() → {Buffer|null}
  getDecimal() → {Decimal|null}
  getIRISList() → {IRISList|null}
  getNumber() → {Number|null}
  getObject() → {any|null}
  getString() → {String|null}

IRISReference.getType() Gets the type hint of the IRISReference.

  getType() → {IRISReference.Type}

IRISReference.setType() Sets the type hint of the IRISReference.

  setType(type)

parameters:

• type — type hint that describes the type of the value.

  • IRISReference.Type.ANY

  • IRISReference.Type.BOOLEAN

  • IRISReference.Type.BYTES

  • IRISReference.Type.DECIMAL

  • IRISReference.Type.BIGINT

  • IRISReference.Type.NUMBER

  • IRISReference.Type.IRISLIST

  • IRISReference.Type.STRING

IRISGlobalNode.clear() deletes the specified global from the InterSystems IRIS server.

  clear()

class.delete() Removes the value at the specified subscript from the IRISGlobalNode.

  delete(subscript)

parameters:

• subscript — the location of the value to remove.

IRISGlobalName.entries() returns an Iterator of the IRISGlobalNode that yields subscript-value pairs.

  entries() → {Iterator}

IRISGlobalNode.foreach() iterates over the IRISGlobalNode and executes the specified callback function.

  foreach(callback, thisArg)

parameters:

• callback — the callback function.

• thisArg — the argument to use as this for the callback.

IRISGlobalNode.get() retrieves the value from the specified subscript.

  get(subscript, default_value) → {any}

parameters:

• subscript — the subscript to return.

• default_value — the default value to return if the subscript does not exist.

IRISGlobalNode.has() whether a value exists at the specified subscript.

  has(subscript) → {Boolean}

parameters:

• subscript — the subscript to check.

IRISGlobalNode.keys() returns an Iterator which, if iterated over, returns the node's subscripts.

  keys() → {Iterator}

IRISGlobalNode.node() returns an IRISGlobalNode that represents the subnode at the specified subscript.

  node(subscript) → {IRISGlobalNode}

parameters:

• subscript — the subscript of the node to return.

IRISGlobalNode.nodeEntries() returns an Iterator for the subscript-subnode pairs of the IRISGlobalNode.

  node(subscript) → {IRISGlobalNode}

IRISGlobalNode.nodeEntries() returns an Iterator for the subnodes of the IRISGlobalNode.

  node(subscript) → {IRISGlobalNode}

IRISGlobalNode.reversed() returns an Iterator which, if iterated over, returns the node's subscript-value pairs in reverse order.

  reversed() → {Iterator}

IRISGlobalNode.set() adds or updates the value at the specified subscript.

  set(subscript, value)

parameters:

• subscript — the subscript to add or update.

• value — the new value.

IRISGlobalNode.subscripts() an alias for IRISGlobalNode.keys().

  subscripts() → {Iterator}

Iterator.next() positions the iterator at the next sibling node in collation order and returns an object containing done and value properties. If the iterator is at end then done is true, otherwise it is false.

next() → {any}

When done is false, the return type of the value property can be set by any of the following methods:

• entries() causes value to return as an array where value(0) is the subscript and value(1) is the node value (this array is the default when the iterator is created).

• nodeEntries() causes value to return as an array where value(0) is the subscript and value(1) is a IRISGlobalNode.

• nodes() causes value to return instances of IRISGlobalNode.

• keys() causes value to return only the current subscript.

• values() causes value to return only the value of the current node.

Iterator.startFrom() sets the iterator's starting position to the specified subscript. The starting position does not have to be a valid subnode. Returns this for chaining.

startFrom(subscript) → {external:"intersystems-iris-native".Iterator}

parameter:

• subscript — the subscript to use as a starting point. Does not have to specify an existing node.

The iterator will not point to a node until you call next() to advance to the next existing node in collating order.

Iterator.reversed() toggles iteration direction between forward and reverse collation order. By default, the iterator is set to forward iteration when it is defined. Returns this for chaining.

reversed() → {external:"intersystems-iris-native".Iterator}

Iterator.entries() specifies that next().value should be an array containing the node subscript (value(0)) and node value (value(1)). Returns this for chaining.

entries() → {external:"intersystems-iris-native".Iterator}

Iterator.nodeEntries() specifies that next().value should be an array containing the node subscript (value(0)) and a IRISGlobalNode (value(1)). Returns this for chaining.

entries() → {external:"intersystems-iris-native".Iterator}

Iterator.nodes() specifies that next().value should be instances of IRISGlobalNode. Returns this for chaining.

entries() → {external:"intersystems-iris-native".Iterator}

Iterator.keys() specifies that next().value should contain only the node subscript (key). Returns this for chaining.

keys() → {external:"intersystems-iris-native".Iterator}

Iterator.values() specifies that next().value should contain only the node value. Returns this for chaining.

values() → {external:"intersystems-iris-native".Iterator}