Calling Class Methods from Node.js

This section describes methods of class Iris that allow you to call ObjectScript class methods directly from your Node.js application. See the following sections for details and examples:

Calling Methods from Node.js — demonstrates how to call methods of ObjectScript classes.
Passing Arguments by Reference — demonstrates how to pass method arguments with the IRISReference class. .

Calling Class Methods from Node.js

The classMethodValue() and classMethodVoid() methods will work for most purposes, but if a specific return type is needed, the following Iris.classMethodValue() typecast methods are also available: classMethodBoolean(), classMethodBytes(), classMethodDecimal(), classMethodFloat(), classMethodIRISList(), classMethodInteger(), classMethodObject(), and classMethodString().

These methods all take string arguments for class_name and method_name, plus 0 or more method arguments.

The code in the following example calls class methods of several datatypes from an ObjectScript test class named User.NativeTest. (see listing “ObjectScript Class User.NativeTest” at the end of this section).

Node.js calls to ObjectScript class methods

The code in this example calls class methods of each supported datatype from ObjectScript test class User.NativeTest (listed immediately after this example). Assume that variable irisjs is a previously defined instance of class Iris and is currently connected to the server (see “Creating a Connection in Node.js”).

  const className = 'User.NativeTest';
  let cmValue = "";
  let comment = "";

  comment = ".cmBoolean() tests whether arguments 2 and 3 are equal: "
  cmValue = irisjs.classMethodBoolean(className,'cmBoolean',2,3);
  console.log(className + comment + cmValue);

  comment = ".cmBytes() returns integer arguments 72,105,33 as a byte array (string value 'Hi!'): "
  cmValue = irisjs.classMethodBytes(className,'cmBytes',72,105,33); //ASCII 'Hi!'
  console.log(className + comment + cmValue);

  comment = ".cmString() concatenates 'Hello' with argument string 'World': "
  cmValue = irisjs.classMethodString(className,'cmString','World');
  console.log(className + comment + cmValue);

  comment = ".cmLong() returns the sum of arguments 7+8: "
  cmValue = irisjs.classMethodInteger(className,'cmLong',7,8);
  console.log(className + comment + cmValue);

  comment = ".cmDouble() multiplies argument 4.5 by 1.5: "
  cmValue = irisjs.classMethodFloat(className,'cmDouble',4.5);
  console.log(className + comment + cmValue);

  comment = ".cmList() returns a $LIST containing arguments 'The answer is ' and 42: "
  cmValue = irisjs.classMethodIRISList(className,"cmList","The answer is ",42);
  console.log(className + comment+cmValue.get(1)+cmValue.get(2) )

  comment = ".cmVoid() assigns argument value 75 to global node ^cmGlobal: "
  try {
    irisjs.kill('cmGlobal') // delete old ^cmGlobal if it exists
    irisjs.classMethodVoid(className,'cmVoid',75);
    cmValue = irisjs.get("cmGlobal");  //get current value of ^cmGlobal
  }
  catch {cmValue = 'method failed.'}
  console.log(className + comment + cmValue);

This example demonstrates the classMethodValue() Typecast Methods for each supported type. It omits classMethodValue() (which returns an untyped value) and classMethodObject() (which is demonstrated in “Controlling Database Objects with Node.js”).

ObjectScript Class User.NativeTest

To run the previous example, this ObjectScript class must be compiled and available on the server:


Class User.NativeTest Extends %Persistent
  {

  ClassMethod cmBoolean(cm1 As %Integer, cm2 As %Integer) As %Boolean
  {
     Quit (cm1=cm2)
  }

  ClassMethod cmBytes(cm1 As %Integer, cm2 As %Integer, cm3 As %Integer) As %Binary
  {
     Quit $CHAR(cm1,cm2,cm3)
  }

  ClassMethod cmString(cm1 As %String) As %String
  {
     Quit "Hello "_cm1
  }

  ClassMethod cmLong(cm1 As %Integer, cm2 As %Integer) As %Integer
  {
     Quit cm1+cm2
  }

  ClassMethod cmDouble(cm1 As %Double) As %Double
  {
     Quit cm1 * 1.5
  }

  ClassMethod cmVoid(cm1 As %Integer)
  {
     Set ^cmGlobal=cm1
     Quit
  }

  ClassMethod cmList(cm1 As %String, cm2 As %Integer)
  {
     Set list = $LISTBUILD(cm1,cm2)
     Quit list
  }
}

You can test these methods by calling them from the Terminal. For example:

USER>write ##class(User.NativeTest).cmString("World")
Hello World

Note:

Functions and Procedures

Earlier versions of the Node.js Native SDK provided methods that directly accessed ObjectScript functions and procedures. These methods have been removed due to security concerns. Functions and procedures can still be called indirectly by making them available as methods in an ObjectScript wrapper class.

Passing Arguments by Reference

Most of the classes in the InterSystems Class Library use a calling convention where methods only return a %StatusOpens in a new tab value. The actual results are returned in arguments passed by reference. The Node.js Native SDK supports pass by reference for both methods and functions by assigning the argument value to an instance of class IRISReference and passing that instance as the argument:

  const IRISNative = require('intersystems-iris')
  var ref_object = new IRISNative.IRISReference(null) // set inital value to 0
  var status = irisjs.classMethodObject("%SomeClass","SomeMethod", arglist, ref_object);
  var returned_value = ref_object.getValue;  // get the method result

The following example calls a standard Class Library method:

Using pass-by-reference arguments

This example calls %SYS.DatabaseQuery.GetDatabaseFreeSpace()Opens in a new tab to get the amount of free space (in MB) available in the iristemp database.

  const IRISNative = require('intersystems-iris')
  var freeMB = new IRISNative.IRISReference(null) // set inital value to 0
  const dir = "C:/InterSystems/IRIS/mgr/iristemp" // directory to be tested
  var value = "error"
  var status = 0

  console.log("Type of freeMB = "+ (typeof freeMB) + ", value = " + freeMB.getValue())
  try{
    console.log("Calling %SYS.DatabaseQuery.GetDatabaseFreeSpace()... ")
    status = irisjs.classMethodObject("%SYS.DatabaseQuery","GetDatabaseFreeSpace",dir,freeMB)
    value = freeMB.getValue()
  } catch {
    console.log("Call to class method GetDatabaseFreeSpace() returned error:")
  }
  console.log("(status=" + status + ") Free space in " + dir + " = " + value + "MB\n")
}

prints:

Type of freeMB=str(type(freeMB)), value=null
Calling %SYS.DatabaseQuery.GetDatabaseFreeSpace()...
(status=1) Free space in C:/InterSystems/IRIS/mgr/iristemp = 10MB

Controlling Database Objects from Node.js

Introduction to the Native SDK for Node.js