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.

   isUsingSharedMemory() → {boolean}

Iris.classMethodValue() 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 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.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.

  classMethodBoolean(className, methodName, ...args) → {boolean}
  classMethodBytes(className, methodName, ...args) → {Buffer}
  classMethodDecimal(className, methodName, ...args) → {Decimal}
  classMethodFloat(className, methodName, ...args) → {number}
  classMethodInteger(className, methodName, ...args) → {number}
  classMethodIRISList(className, methodName, ...args) → {IRISList}
  classMethodNumber(className, methodName, ...args) → {number}
  classMethodObject(className, methodName, ...args) → {any}
  classMethodString(className, methodName, ...args) → {string}

parameters:

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

• methodName — name of the class method.

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

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.

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

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.close() closes the Iris object.

  close()

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.

  getBoolean(globalName, ...subscripts) → {boolean}
  getBytes(globalName, ...subscripts) → {ArrayBuffer}
  getDecimal(globalName, ...subscripts) → {Decimal}
  getFloat(globalName, ...subscripts) → {number}
  getInteger(globalName, ...subscripts) → {number}
  getList(globalName, ...subscripts) → {IRISList}
  getIRISList(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 string for this version of the Native SDK. Also see getServerVersion().

  getAPIVersion() → {string}

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

  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 "" for neither. An empty string is the default mode (unshared 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) → {null|string}

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.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 new value may be bool, bytes, bytearray, Decimal, float, int, str, or 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 lockMode ("S" for shared, "E" for escalating lock). See “Concurrency Control with Node.js” for more information.

  unlock(lockMode, lockReference, ...subscript)

parameters:

• lockMode — one of the following strings: "S" for shared lock, "E" for escalating lock, "SE" for both, or "" for neither. An empty string is the default mode (unshared and non-escalating).

• 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

IRISObject.close() releases this instance of IRISObject.

  close()

IRISObject.get() fetches a property value of the proxy object.

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

  get(propertyName) → {null|any}

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.

  getBoolean(propertyName) → {null|boolean}
  getBuffer(propertyName) → {null|Buffer}
  getDecimal(propertyName) → {null|Decimal}
  getFloat(propertyName) → {null|number}
  getInteger(propertyName) → {null|number}
  getIRISList(propertyName) → {null|IRISList}
  getNumber(propertyName) → {null|number}
  getObject(propertyName) → {null|any}
  getString(propertyName) → {null|string}

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.

  invokeBoolean(methodName, ...arguments) → {boolean}
  invokeBytes(methodName, ...arguments) → {Buffer}
  invokeDecimal(methodName, ...arguments) → {Decimal}
  invokeFloat(methodName, ...arguments) → {number}
  invokeInteger(methodName, ...arguments) → {integer
  invokeIRISList(methodName, ...arguments) → {IRISList}
  invokeNumber(methodName, ...arguments) → {number}
  invokeObject(methodName, ...arguments) → {any}
  invokeString(methodName, ...arguments) → {string}

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 proxy object.

  set (propertyName, propertyValue)

parameters:

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

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