Learning
Community
Open Exchange
Global Masters
InterSystems IRIS Data Platform 2019.3 / Application Development / Using the Native API for Node.js / Native API Quick Reference for Node.js
Previous section   

Native API Quick Reference for Node.js

This chapter is a quick reference for the following classes, which are all members of module external:"intersystems-iris-native"
Note:
This chapter is intended as a convenience for readers of this book, but it is not the definitive reference for the Native API. For the most complete and up-to-date information on these classes, see the online API documentation.

List of Methods by Usage

Class Connection
The Connection class encapsulates a connection to the server. Instances of Connection are created and connected to the server by external:"intersystems-iris-native" method createConnection().
Class Iris
The Iris class provides most of the Native API functionality. Instances of Iris are created by Connection.createIris(). Methods are listed below, organized by usage:
Class Iris: Global Iteration and Management
  • getAPIVersion() — returns the version string for this version of the Native API.
  • getServerVersion() — returns the version string for the currently connected server.
  • increment() — increments the value of a global node by the specified amount.
  • isDefined() — checks if a global node exists, and if it contains data.
  • iterator() — returns an instance of Iterator.
  • kill() — kills the global node including any descendants.
Class Iris: Node Value Accessors
  • get() — returns the specified node value
  • getBoolean() — returns a node value as boolean
  • getBytes() — returns a node value as an ArrayBuffer
  • getNumber() — returns a node value as a number
  • getString() — returns a node value as a string
Class Iris: Transactions and Locking
  • lock() — performs an incremental lock on the global, returns true on success.
  • unlock() — performs an immediate or deferred unlock on the global.
  • releaseAllLocks() — releases all locks associated with the session.
  • getTLevel() — returns the current transaction level (0 if not in a transaction).
  • tCommit() — commits the current transaction and decrements the transaction level.
  • tRollback() — rolls back all open transactions in the session.
  • tRollbackOne() — rolls back the current level transaction only.
  • tStart() — starts a transaction and increments the transaction level.
Class Iris: ClassMethod and Function Calls
  • classMethodValue() — calls a user defined ObjectScript method and gets the returned value
  • classMethodVoid() — calls a user defined ObjectScript method, ignoring any returned value
  • function() — calls a function of a user defined ObjectScript routine and gets the returned value
  • procedure() — calls a procedure of a user defined ObjectScript routine
Class Iterator
The Iterator class provides methods to iterate over a set of nodes. Instances of Iterator are created by Iris.iterator().
  • next() — positions the iterator at the next sibling node.
  • startFrom() — sets starting position to the specified subscript.
  • reversed() — toggles iteration between forward and reverse collation order.
  • entries() — sets return type to an array containing subscript and node value.
  • keys() — sets return type to return the node subscript (key) only.
  • values() — sets return type to return the node value only.

Class Connection

Class Connection is a member of external:"intersystems-iris-native". Instances of Connection are created by intersystems-iris-native method createConnection().
createConnection()
intersystems-iris-native createConnection() establishes a connection to the server.
(static) createConnection(connectionInfo) → {external:"intersystems-iris-native".Connection}
parameters:
  • connectionInfo — Object containing connection properties. Valid properties of connectionInfo are:
    • hostrequired string containing the address of the host machine
    • portrequired integer specifying the port number
    • nsrequired string containing the database namespace
    • user — string containing the user name
    • pwd — string containing the password
    • sharedmemory — boolean indicating whether to use shared memory if available (default is true).
    • timeout — integer specifying the number of milliseconds to wait before the connection attempt times out (default is 10000).
    • logfile — string specifying the full path and name of a log file for this connection. If not specified, no log file will be written.
    For example, the following code fragment defines all properties of connectionInfo and creates an instance of Connection named conn:
      const IRISNative = require('intersystems-iris-native')
    
      let connectionInfo = {
        host: '127.0.0.1',
        port: 51773,
        ns: 'USER',
        user: '_SYSTEM',
        pwd: 'SYS',
        sharedmemory: true
        timeout: 5,
        logfile: 'C:\temp\mylogfile.log'
      };
    
      const conn = IRISNative.createConnection(connectionInfo);
    
close()
Connection.close() closes the connection to the server.
close()
createIris()
Connection.createIris() returns an instance of class Iris connected to the server by this Connection.
createIris() →→ {external:"intersystems-iris-native".Iris}
isClosed()
Connection.isClosed() returns true if the connection is currently closed, false if the connection is currently open.
isClosed() → {boolean}
isUsingSharedMemory()
Connection.isUsingSharedMemory() returns true if the connection is using shared memory, false if it is not.
isUsingSharedMemory() → {boolean}

Class Iris

Class Iris is a member of external:"intersystems-iris-native". Instances of Iris are created by calling Connection.createIris().
The main IRIS Native API is implemented by the IRIS class. Functions implemented by IRIS are global functions, function and procedure calls, locks, and transactions.
classMethodValue()
Iris.classMethodValue() calls a class method, passing 0 or more arguments and returning the called method’s return value..
classMethodValue(methodName, ...args) → {any}
parameters:
  • className — fully qualified name of the class to which the called method belongs.
  • methodName — name of the class method.
  • args — 0 or more method arguments of supported types (see “Calling ObjectScript Methods and Functions”). Trailing arguments may be omitted.
classMethodVoid()
Iris.classMethodVoid() calls a class method, passing 0 or more arguments and returning nothing.
classMethodVoid(methodName, ...args)
parameters:
  • className — fully qualified name of the class to which the called method belongs.
  • methodName — name of the class method.
  • args — 0 or more method arguments of supported types (see “Calling ObjectScript Methods and Functions”). Trailing arguments may be omitted.
function()
Iris.function() calls a function, passing 0 or more arguments and returning the called function’s return value.
function(functionName, routineName, ...args) → {any}
parameters:
  • functionName — name of the function to call
  • routineName — name of the routine containing the function.
  • args — 0 or more function arguments of supported types (see “Calling ObjectScript Methods and Functions”). Trailing arguments may be omitted.
get()
Iris.get() returns the value of the global node. Returns false if node value is an empty string, or null if the specified node address does not have a value.
get(globalName, ...subscripts) → {any}
parameters:
  • globalName — global name
  • subscripts — array of subscripts specifying the target node
getAPIVersion()
Iris.getAPIVersion() returns the Native API version string.
getAPIVersion() → {string}
getBoolean()
Iris.getBoolean() returns the node value as a boolean. Returns false if node value is an empty string, or null if the specified node address does not have a value.
getBoolean(globalName, ...subscripts) → {boolean}
parameters:
  • globalName — global name
  • subscripts — array of subscripts specifying the target node
getBytes()
Iris.getBytes() returns the node value as an ArrayBuffer. Returns false if node value is an empty string, or null if the specified node address does not have a value.
getBytes(globalName, ...subscripts) → {ArrayBuffer}
parameters:
  • globalName — global name
  • subscripts — array of subscripts specifying the target node
getNumber()
Iris.getNumber() returns the node value as a number. Returns false if node value is an empty string, or null if the specified node address does not have a value.
getNumber(globalName, ...subscripts) → {number}
parameters:
  • globalName — global name
  • subscripts — array of subscripts specifying the target node
getServerVersion()
Iris.getServerVersion() returns the version string of the currently connected server.
getServerVersion() → {string}
getString()
Iris.getString() returns the node value as a string. Returns false if node value is an empty string, or null if the specified node address does not have a value.
getString(globalName, subscripts) → {string}
parameters:
  • globalName — global name
  • subscripts — array of subscripts specifying the target node
getTLevel()
Iris.getTLevel() returns the level of the current nested transaction. Returns 1 if there is only a single transaction open. Returns 0 if there are no transactions open. This is equivalent to fetching the value of the $TLEVEL special variable. See “Transactions and Locking” for more information and examples.
getTLevel() → {number}
increment()
Iris.increment() increments the specified node by the integer value of incrementBy. If the specified node address does not have a value, then the node will be created and its value set to the value of incrementBy. Returns the new integer value of the node.
increment(incrementBy, globalName, ...subscript) → {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 — array of subscripts specifying the target node
isDefined()
Iris.isDefined() checks if a global exists and contains data (see $DATA). Returns 0 if the node does not exist, 1 if the global node exists and contains data. 10 if the node is valueless but has descendants. 11 if it has data and descendants. See “Testing for Child Nodes and Node Values” for more information and examples.
isDefined(globalName, ...subscript) → {number}
parameters:
  • globalName — global name
  • subscripts — array of subscripts for this node
iterator()
Iris.iterator() returns an Iterator object (see “Class Iterator”) for the specified node.
iterator(globalName, ...subscript) → {external:"intersystems-iris-native".Iterator}
parameters:
  • globalName — global name
  • subscripts — array of subscripts specifying the target node
kill()
Iris.kill() kills the global node including any descendants.
kill(globalName, ...subscript)
parameters:
  • globalName — global name
  • subscripts — array of subscripts for this node
lock()
Iris.lock() locks the global, returns true on success. This method performs an incremental lock, not the implicit unlock-before-lock feature that is offered in ObjectScript.
lock(lockType, timeout, lockReference, ...subscript) → {boolean}
parameters:
  • lockMode — character S for shared lock or E for escalating lock.
  • timeout — amount to wait to acquire the lock in seconds
  • 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 — array of subscripts for this node
procedure()
Iris.procedure() calls a procedure, passing 0 or more arguments.
procedure(procedureName, routineName, ...args)
parameters:
  • procedureName — name of the procedure to call.
  • routineName — name of the routine containing the procedure.
  • args — 0 or more procedure arguments of supported types (see “Calling ObjectScript Methods and Functions”). Trailing arguments may be omitted.
releaseAllLocks()
Iris.releaseAllLocks() releases all locks associated with the session.
releaseAllLocks()
set()
Iris.set() sets the current node to a value of a supported datatype (or "" if the value is null):
set(value, globalName, ...subscript)
parameters:
  • value — value of a supported datatype (null value sets global to "").
  • globalName — global name
  • subscripts — array of subscripts for this node
tCommit()
Iris.tCommit() commits the current transaction and decrements the transaction level. See “Transactions and Locking” for more information and examples.
tCommit()
tRollback()
Iris.tRollback() rolls back all open transactions in the session. See “Transactions and Locking” for more information and examples.
tRollback()
tRollbackOne()
Iris.tRollbackOne() rolls back the current level transaction only. If this is a nested transaction, any higher-level transactions will not be rolled back. See “Transactions and Locking” for more information and examples.
tRollbackOne()
tStart()
Iris.tStart() starts a transaction and increments the transaction level. See “Transactions and Locking” for more information and examples.
tStart()
unlock()
Iris.unlock() unlocks the global. This method performs an incremental unlock, not the implicit unlock-before-lock feature that is also offered in ObjectScript.
unlock(lockMode, lockReference, ...subscript)
parameters:
  • lockMode — string containing lock type (S for Shared or E for Escalating) and unlock type (I for an Immediate unlock or D for Deferred).
  • 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 — array of subscripts for this node

Class Iterator

Class Iterator is a member of external:"intersystems-iris-native". Instances of Iterator are created by calling Iris.iterator(). See “Finding Nodes in a Global Array” for more details and examples.
next()
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).
  • keys() causes value to return only the current subscript.
  • values() causes value to return only the value of the current node.
startFrom()
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.
reversed()
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}
entries()
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}
keys()
Iterator.keys() specifies that next().value should contain only the node subscript (key). Returns this for chaining.
keys() → {external:"intersystems-iris-native".Iterator}
values()
Iterator.values() specifies that next().value should contain only the node value. Returns this for chaining.
values() → {external:"intersystems-iris-native".Iterator}
Previous section