IRIS Native API for ObjectScript

Article

Robert Cemper · Sep 14, 2020 3m read

It seems to me that for some reason this didn't make its way to the official documentation
and seems to be rather unknown though implemented already in IRIS 2020.1

Thanks to @Dan Pasco I got a hint on the classes involved.
I used the recommended sequence of how to use it.
it is all directly taken from Class Reference and I just collected it to create a first overview.

The Native API for ObjectScript follows the API used on other language platforms. It starts with a static API that allows the user to connect to an IRIS Namespace, either local or remote, using an Iris Connection. The connection interface allows the user to then instantiate the IRIS Native API class (%Net.DB.Iris). That instance can then be used to access IRIS Global Arrays, manage transactions, invoke functions and methods implemented in routines or classes, and instantiate remote iterators.

%Net.DB.DataSource

This class implements the IRIS Native API for Object Script DataSource interface.
At this time that interface consists solely of the CreateConnection method.

CreateConnection accepts url, port,namespace, user, and pwd parameters. Refer to %Net.DB.Connection for more information on these parameters. CreateConnection() returns an instance of %Net.DB.Connection.

host	input	The host name or address, defaults to 127.0.0.1
port	input	The port on which to connect
namespace	input	The namespace to connect to
user	input	The user's name
pwd	input	User's password
timeout	input	The number of seconds to wait for the connection to be established. Optional.
logfile	input	The name of the file to be used for logging. If specified, connection activity will be logged to that file. Optional.
	return	An oref referencing an instance of %Net.DB.Connection

%Net.DB.Connection

This class implements the IRIS Native API for Object Script Connection interface.
This class should never be instantiated directly, only through %Net.DB.DataSource using the CreateMethod() function.

The public interface for this class includes only those items specified here. All other members are internal.

Host	property	The host specified when establishing the connection
Port	property	The port that this connection is connected.
Namespace	property	The namespace that this connection is connected.
Timeout	property	The timeout value specified establishing the connection
IsClosed	method	Returns true if this connection instance is no longer connected.
Close	method	Close this connection.
CreateIris	method	Returns an instance of %Net.DB.Iris.

%Net.DB.Iris

This class implements the primary set of functions IRIS Native API for Object Script.
The only other members of the IRIS Native API that are not implemented by this class
are implemented by %Net.DB.DataSource and %Net.DB.Connection.
This class should never be instantiated directly.
The proper way to instantiate this class is to invoke the CreateIris() method using an instance of %Net.DB.Connection.

Summary of methods:

GitHub

Robert Cemper · Sep 14, 2020

BIG THANKS to @Dan Pasco for sharing this example:

The test is simple - I am running in the 2020R1 instance, namespace USER and there are no classes runnable in this namespace - just a clean, new install. I have several other instances running, all different versions/build numbers. I am testing against my XDBC instance which is currently labeled as 2020.4 (obviously not yet released but the IRIS Native code is essentially the same as in 2020.1). The XDBC instance is listening on port 51780. First, proof this doesn't work locally.

USER>write ##class(Sample.Person).CurrentAge($h-35000)                 

WRITE ##CLASS(Sample.Person).CurrentAge($H-35000)
^
<CLASS DOES NOT EXIST> *Sample.Person

And then, attempt the same function using the IRIS Native connection to the XDBC instance.

USER>set host="localhost",port=51780,namespace="USER",user="_SYSTEM",pwd="SYS" 

USER>set connection = ##class(%Net.DB.DataSource).CreateConnection(host, port, namespace, user, pwd)

USER>set iris = connection.CreateIris()                                                             

USER>write iris.ClassMethodValue("Sample.Person","CurrentAge",$h-35000)                             
95

7 1

ClassMethodValue	ClassMethodVoid	Function	Get
GetBoolean	GetNext	GetObject	GetRecordMetadata
GetSchema	GetTLevel	Increment	IsDefined
Kill	Lock	Procedure	ReleaseAllLocks
Set	TCommit	TRollback	TRollbackOne
TStart	Unlock