Intro to InterSystems IRIS Classes

The code used in InterSystems IRIS is organized in classes. A class defines a structure for data and behavior, combining stored data with methods that implement behavior. Almost every aspect of InterSystems IRIS development relies on classes, including storing data in databases, manipulating objects, interopability components and internal configuration.

IRIS class definitions are stored in files with the .cls extension and written using ObjectScript (with optional embedded SQL, Python and XML blocks). Once defined, a class can be compiled into the IRIS environment, making it available as an object, as a persistent table, or as part of a larger application.

This guide introduces fundamental elements of IRIS classes, then demonstrates their use through practical and worked examples.

Classes have components, such as properties, parameters, methods and class methods.

The following is a list of some common class components with a brief explanation, many of these features will be demonstrated in the example class below:

• Parameter: Constant values, set within a class definition.
• Property: Variable which can be set in class objects. These define datatypes and storage behaviour.
• ClassMethod: Function which does not require a class object to be run.
• Method: Function that can only be run from an instantiated class object.
• Query: Pre-written SQL query.
• XData: Data block, normally consisting of XML data, but could also be other formats like JSON or YAML. Used for specific purposes like mapping REST endpoints to methods orcreating business process rules.

Classes can inherit from superclasses. Superclasses will provide classes with behavior, storage logic and metadata which are important or specialized for a specific use, for example the %JSON.Adaptor gives ability to import or export JSON strings. Classes can also inherit from multiple superclasses.

The most important superclasses to be aware of are %RegisteredObject, and its child class %Persistent.

%RegisteredObject allows the class to be instantiated into an object, which can be used to store values as properties and run `Methods`. Only classes which inherit from %RegisteredObject or a sub-class of %RegisteredObject (including %Persistent and %SerialObject) can be instantiated into an object.

%Persistent classes are classes which can be saved into the database, providing persistent storage and SQL projection (more on this below).

The Example Class section below demonstrates how a class can be used within InterSystems IRIS, including accessing parameters, properties and the difference between methods and class methods. Before jumping to this, its recommended to set up a demonstration environment and compile the example class locally. This section demonstrates how to setup the environment and compile the class.

The easiest method to run a sandbox instance of InterSystems IRIS is to use InterSystems IRIS Community Edition in a docker container. The command below will start a container. For more information on setting up InterSystems IRIS Community Edition see Get InterSystems IRIS Community with Docker or Get InterSystems IRIS Community Edition with an Install Kit.

docker run --name my-iris --publish 1972:1972 --publish 52773:52773 -d intersystems/iris-community:latest-em

Classes need to be imported into the InterSystems IRIS instance and compiled before usage, which can be done in several ways. The two methods below are the quickest methods to do this using the management portal GUI or from the terminal.

For active development, it is highly recommended to connect to InterSystems IRIS from VS Code, which allows easy importing, automatic compiling after saving and direct editing on the InterSystems IRIS server. However, this requires more setup than the easy import methods below.

The Management Portal can also be used to import classes directly. This method is less convenient for continuous editing, but can be effective for quickly adding files into your instance (like the example classes below).

To import from the management portal, save the class as a file locally, then open the management portal ( http://localhost:52773/csp/sys/%25CSP.Portal.Home.zen if running locally with the default port), and navigate to System Explorer -> Classes -> Go.

This will bring up a page of all the compiled classes on your instance. Ensure you are in the USER namespace, then click Import at the top of the page to bring up the class importer wizard. Then you can choose to upload a file on your system, select your file from the browser pop-up.

The default settings are fine for basic importing and compilation, so you just need to select a file and click Import.

You can also compile classes from the IRIS terminal, which requires the file to be on the same machine as your InterSystems IRIS instance. If running in a docker container, this can be done with a simple docker copy, or by mounting volumes when you first run the container. The docker copy method is shown below:

docker cp /path/to/myclass.cls my-iris:/tmp/myclass.cls

Then, to compile the class, start an IRIS Terminal:

docker exec -it my-iris iris session iris

And run:

// Ensure you are in the correct namespace
set $NAMESPACE = "USER"

// Compile using %SYSTEM.OBJ
do ##class(%SYSTEM.OBJ).Import("/tmp/myclass.cls", "cuk")

The "cuk" in this command are compiler flags ( c is compile, u is update only (skip up-to-date classes) and k is keep source file).

Many features of classes and ObjectScript are demonstrated in the example class below:

/* Class definition
packagename is the directory containing the .cls file
*/
Class packagename.ClassName Extends %RegisteredObject
{
	// A property is a persistent variable.  
	// As %String states that the property is a string
	// Required is a keyword argument, meaning the object cannot be saved without this variable
	Property VariableName As %String [Required]; 

	// A Parameter is a constant
	// It's standard practice to use all caps for parameters
	Parameter CONSTANT = 2;
	
	// A Class Method is called directly from the class, without needing to be instantiated
	// Takes two integers in, returns a string out
	ClassMethod AddNums(param1 As %Integer, param2 As %Integer) As %String
	{
		// Set operator assigns the value 
		set sum = param1 + param2 
		
		// Use _ operator to join strings
		set output = "The sum of "_param1_" and "_param2_" is "_sum
		return output
	}
	
	// A Method is called from an instantiated object from the class
	Method FizzBuzz(max As %Integer)
	{
		// Loop with  iterator=start : step : Maximum
		// ..# refers to a Parameter of the parent class
		for i=1 : ..#CONSTANT : max
		{			
			// WRITE operator outputs result to terminal
			// ! operator creates a new line
			write !, i
			
			// Basic Conditional Format
			// # is modulo operator (remainder)
			if (i # 3 = 0) && (i # 5 = 0) {
				write "  FizzBuzz"
			} 
			elseif (i # 3 = 0){
				write "  Fizz"
			} 
			elseif (i # 5 = 0){
				write "  Buzz"
			}
			else{ 
				// .. denotes a property or method of the parent class
				write "  "_..VariableName
			}
		}
	}
}

You can call a ClassMethod without instantiating a class, using the do operator to run a method and ##class() to reference a class.

do ##class(packagename.ClassName).AddNums(1, 2)

- The sum of 1 and 2 is 3

You can instantiate a registerded object with:

set object = ##class(packagename.ClassName).%New()

To use properties:

set object.VariableName = "Hello World"
write object.VariableName // prints Hello World to terminal

A method can be used from an object:

write object.FizzBuzz(15)

This outputs the following:

1  Hello World 
3  Fizz
5  Buzz
7  Hello World
9  Fizz
11  Hello World
13  Hello World
15  FizzBuzz

This function uses the CONSTANT parameter as a step size, the # modulo operator to calculate a remainder, which is used for the conditional, and the VariableName property which was set above to output Hello World.

A %Persistent class is a class that can be saved directly into the database. Properties of a persistent class are projected into columns of a relational table, which can then be queried with SQL. A persistent class is created by extending (inheriting from) the %Persistent superclass. Persistent classes can also have methods, class methods, parameters or other class components.

Class packagename.Person Extends %Persistent{

	// Person's Name
	// As %String defines the data-type
	Property Name As %String;  
	
	// Person's Age (in Years)
	Property Age As %Integer; 
}

Persistent classes can be accessed as objects as follows:

set person = ##class(packagename.Person).%New()
set person.Name = "John Smith"
set person.Age = 25
do person.%Save()

Persistent classes are automatically given an ID upon saving. We can access the entry at a specific ID using %OpenId

set person2 = ##class(packagename.Person).%OpenId(1)
write person2.Name // Outputs "John Smith"

A Persistent class can then be queried using SQL.

There are a number of methods for calling SQL, on the database, which are detailed in other tutorials, for example a query can be run from client-side applications connected through ODBC, JDBC or Python DB-API, from the Management Portal SQL explorer or server-side code.

SELECT Name, Age FROM packagename.Person

This would return the following table: