Learning
Community
Open Exchange
Global Masters
InterSystems IRIS Data Platform 2019.3 / Application Development / Using the Native API for Python / Calling ObjectScript Methods and Functions
Previous section   Next section

Calling ObjectScript Methods and Functions

This chapter describes methods of class iris that allow an application to call class methods and functions from user defined ObjectScript classes and routines.
Note:
Although these methods can also be used with InterSystems classes defined in the Class Library, best practice is to call them indirectly, from within a user defined class or routine.
Many class methods return only a status code, passing the actual results back in an argument (which cannot be accessed by the Native API). System defined functions (listed under ObjectScript Functions in the ObjectScript Reference) cannot be called directly.

Class Method Calls

The following Native API methods call a specified ObjectScript class method.
These methods take string arguments for className and methodName, plus 0 or more method arguments. Trailing arguments may be omitted in argument lists, causing default values to be used for those arguments, either by passing fewer than the full number of arguments, or by passing null for trailing arguments. An exception will be thrown if a non-null argument is passed to the right of a null argument.
The code in the following example calls class methods of several datatypes from an ObjectScript test class named User.NativeTest. (For a listing, see “Sample ObjectScript Methods and Functions” at the end of this chapter).
Calling class methods of User.NativeTest
In this example, assume that iris is an existing instance of class iris, and is currently connected to the server.
className = "User.NativeTest"
cmValue = ""

cmValue = iris.classMethodValue(className,"cmBoolean",False)
print(className,".cmBoolean() returned value: ", cmValue)

cmValue = iris.classMethodValue(className,"cmBytes","byteArray")
print(className,".cmBytes() returned value: ", cmValue)

cmValue = iris.classMethodValue(className,"cmString","Test String")
print(className,".cmString() returned value: ", cmValue)

cmValue = iris.classMethodValue(className,"cmLong",7,8)
print(className,".cmLong() returned value: ", cmValue)

cmValue = iris.classMethodValue(className,"cmDouble",7.56)
print(className,".cmDouble() returned value: ", cmValue)

try:
  iris.classMethodVoid(className,"cmVoid",67)
  cmValue = iris.get("cm1")
except:
  cmValue = "method failed."
print(className,".cmVoid() set global array cm1 to value: ", cmValue)

Function Calls

The following methods call user-defined ObjectScript functions or procedures (see “Callable User-defined Code Modules” in Using ObjectScript).
  • iris.Function() — calls a user-defined function and gets the return value.
  • iris.Procedure() calls a user-defined procedure or function and discards any returned value.
These methods take string arguments for functionName and routineName, plus 0 or more function arguments. Trailing arguments may be omitted in argument lists, causing default values to be used for those arguments, either by passing fewer than the full number of arguments, or by passing null for trailing arguments. An exception will be thrown if a non-null argument is passed to the right of a null argument.
The code in the following example calls functions of several datatypes from an ObjectScript test routine named NativeRoutine. (For a listing of NativeRoutine.mac, see “Sample ObjectScript Methods and Functions” at the end of this chapter).
Calling functions of NativeRoutine.mac
In this example, assume that iris is an existing instance of class iris, and is currently connected to the server.
routineName = 'NativeRoutine'
fnValue = ""

fnValue = iris.function('funcBoolean',routineName,False)
print(routineName, '.funcBoolean() returned value: ', fnValue)

fnValue = iris.function('funcBytes',routineName,'byteArray')
print(routineName, '.funcBytes() returned value: ', fnValue)

fnValue = iris.function("funcString",routineName,"Test String")
print(routineName, '.funcString() returned value: ', fnValue)

fnValue = iris.function('funcLong',routineName,7,8)
print(routineName, '.funcLong() returned value: ', fnValue)

fnValue = iris.function('funcDouble',routineName,7.56)
print(routineName, '.funcDouble() returned value: ', fnValue)

try:
  iris.procedure("funcProcedure",routineName,67)
  fnValue = iris.get("fn1")
except:
  fnValue = 'procedure failed.'
print(routineName, '.funcVoid() set global array fn1 to value: ', fnValue)

Sample ObjectScript Methods and Functions

To run the examples, these ObjectScript class methods and functions must be compiled and available on the server:
ObjectScript Class User.NativeTest
Class User.NativeTest Extends %Persistent
{
  ClassMethod cmBoolean(cm1 As %Boolean) As %Boolean
  {
   quit 0
  }
  ClassMethod cmBytes(cm1 As %String) As %Binary
  {
   quit $C(65,66,67,68,69,70,71,72,73,74)
  }
  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 * 100
  }
  ClassMethod cmVoid(cm1 As %Integer)
  {
   set ^cm1=cm1
   quit
  }
}
ObjectScript Routine NativeRoutine.mac
funcBoolean(fn1) public {
    quit 0
}
funcBytes(fn1) public {
    quit $C(65,66,67,68,69,70,71,72,73,74)
}
funcString(fn1) public {
    quit "Hello "_fn1
}
funcLong(fn1,fn2) public {
    quit fn1+fn2
}
funcDouble(fn1) public {
    quit fn1 * 100
}
funcProcedure(fn1) public {
    set ^fn1=fn1
    quit
}
Previous section   Next section