InterSystems ObjectScript

ObjectScript is the primary programming language used in InterSystems IRIS and other InterSystems products. It provides multiple ways to interact with data: direct access to globals, working through an object model, or executing SQL commands. This flexibility makes it a powerful tool for building high-performance, data-driven applications.

This guide introduces the basic concepts of the language. It is designed for experienced programmers who are new to the syntax of ObjectScript. The aim of this guide is as a quick reference to begin coding in ObjectScript. For detailed documentation, visit the ObjectScript section of the documentation.

• // denotes a comment,  /* */ start and end multi-line comments.
• ObjectScript is primarily held in InterSystems IRIS class methods and instance methods, or run directly from the InterSystems IRIS terminal. For more on ObjectScript classes and how to use them, see Intro to InterSystems IRIS classes

This guide is intended to be used as a reference, but if you would like to code along, you can start a sandbox instance of InterSystems IRIS Community Edition with docker with the following command:

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

Then, open an InterSystems IRIS terminal with:

docker exec -it my-iris iris session iris

Most of this guide can be run in the terminal, however for the multi-line operations like loops and conditionals, you will get syntax errors. Instead, you may wish to create a basic class to run blocks of code as a class method. For information on how to do this see Intro to InterSystems IRIS Classes.

Before beginning, its useful to know that standard ObjectScript operators case insensitive and often use abbreviations. For example the following all represent equivalent commands:

set num = 1
SET num = 1
SeT num = 1
S num=1 
s num=1

Identifiers, like variables are case sensitive (i.e. num ≠ NUM ≠ Num),

In ObjectScript, variables are created automatically when first assigned, and their types are not enforced. They are simply created or edited with the set command. To set the value of a variable, use the set command.

set output = "Hello World!"
set n = 1

Variables are outputted to the terminal with the command write:

write output // writes "Hello World!" to terminal
write output, n //writes "Hello World!1" to Terminal

write doesn't add any blank spaces or line-breaks. If run in a single block (e.g. a method call or loop), the two outputs of the above commands would appear on the same line. To add a line break, the operator ! is used.

write output, !, n
// Writes: 
// Hello World! 
// 1

The _ operator concatenates objects into a string:

write output_" n = "_n 
// writes 
//"Hello World! n = 1"

To create a multi-line string, you can't concatenate the ! operator, instead you use $CHAR(13, 10) as a newline character:

set multiline =  "First Line"_$CHAR(13, 10)_"Second Line"
write multiline

// Writes: 
// First Line
// Second Line

Functions (methods and class methods) are defined in InterSystems IRIS class methods. There is a detailed guide to using classes, which covers class usage. These can be run with the do operator, for example:

//Shows information on system
do ##class(%SYSTEM.OBJ).ShowFlags() 

// Run a generic class
do ##class(packagename.ClassName).ClassMethodName()

Note, the second command will error unless you create that class.

If a method or class method returns values, you use other operators like set or write in combination with these to save a value.

// Write the IRIS version
write ##class(%SYSTEM.Version).GetVersion()

// Save the current user to a new variable
set currentUser = ##class(%SYSTEM.Process).UserName()
write currentUser 

Along with class methods, reusable functions can also be saved as routines. Routines and procedures are fully supported and common in utilities, but are a legacy format which have been superseded by classes. It is recommended that new logic in InterSystems IRIS is written in classes rather than routines. You may still come across utilities and scripts written in routines so familiarity with their usage can be valuable.

Routines are denoted by a leading caret symbol, i.e. ^myRoutine. In some cases, arguments are passed into routines in brackets. Within a single routine file, there can be multiple functions written, each with a different label. These are procedures and can be accessed with the procedure label before the routine name, i.e. procname^myroutine.

Lists are one dimensional data structures, containing position-indexed values. Use $LISTBUILD to construct a list and $LIST functions to access or update individual elements.

// Lists
set mylist = $LISTBUILD("Apple", "Orange", "Pear")

// Accessing list items
write $LIST(mylist, 2) //prints "Orange" (index starts at 1)

There are many functions to extend the capability of lists, including getting and setting specific values, iterating through lists and creating lists from strings. These are described detailed in the Lists page of the documentation.

ObjectScript multi‑dimensional arrays are nested key–value pairs. These can be used for simple key-value dictionaries:

// Arrays 
set myarray(1) = "Hello"
set myarray(2) = "World"
set myarray("Foo") = "bar"

// Accessing array items
write myarray(1), myarray(2) //prints "HelloWorld" 

write myarray("Foo") // prints Bar

Or you can create complex hierarchies. Each key is a subscript (string or number), and multiple subscripts create a tree-like hierarchy structure. They’re dynamic and sparse, meaning you don't need to predeclare size or datatypes and only the nodes you set exist. The example below shows how a number of subscripts can create a tree-like structure with different nodes.

set multiNodeArray(1) = "Hello"
set multiNodeArray(1, "a", 3) = "Foo"
set multiNodeArray(4) = "Bar"

// This creates the following structure

//    multiNodeArray
//    |__ (1) = "Hello"
//    |   |__("a")
//    |       |__ (3) = "Foo"
//    |
//    |__ (4) = "Bar"

The entire content of arrays (and other data structures) can be written with zwrite:

zwrite myarray 

/* Output: 
myarray(1)="Hello"
myarray(2)="World"
myarray("Foo")="bar" 
*/

zwrite multiNodeArray

/* Output: 
multiNodeArray(1)="Hello"
multiNodeArray(1,2,3)="Foo"
multiNodeArray(4)="Bar"
*/

Globals are persistent, multi‑dimensional arrays stored in the IRIS database. They behave like local arrays (sparse, dynamic, nested key–value pairs) but are durable and shared—any process/session in the same namespace can access them. Again, they are created simply by setting a value. The only syntax difference is the leading caret symbol ^ in the name of the global.

set ^myGlobal(1) = "Hello"
set ^myGlobal(1, 2, 3) = "Foo"
set ^myGlobal(4) = "Bar"

zwrite ^myGlobal
/*
^myGlobal(1)="Hello"
^myGlobal(1,2,3)="Foo"
^myGlobal(4)="Bar"
*/

The difference between this example, and the multiNodeArray example above, is that if you were to restart the terminal session (you can end the session with halt), the output of the zwrite command would be the same with ^myGlobal (because it is saved to the database), but nothing would be outputted for multiNodeArray (because it is only locally scoped).

The basic syntax for conditionals is as follows. However, as mentioned in the prerequisites, this type of multi-line operation will cause a syntax error in the terminal, and should instead be run in a class method.

set n = 2 // Change to try other values

if (n = 1){
	write "One"
} elseif (n '= 2){  // add ' as a NOT operator (e.g. does not equal)
	write "n doesn't equal 2"
} 
else {
	write "n must equal two"
}

Any non-zero value is evaluates as true, but 0 or an empty string ( "") evaluate as false. There is no Boolean data type, with 0 or 1 being used to represent true or false.

Conditionals can be added to other commands using inline conditionals. This is shown below:

set n=2

write:n=1 "n equals 1"
 // Does not write anything as condition not fulfilled

write:n=2 "n equals 2" 
// write "n equals 2" because condition fulfilled

write:n'=1 "n doesn't equal 1" 
// writes "n doesn't equal 2"

do:n=1 ##class(%SYSTEM.OBJ).ShowFlags
() // Does not run method because condition not fulfilled

The basic for loop syntax is as follows:

//Basic For loop

// for <iterator> : <step> : <maximum> { ...operations... }

for i=1: 1: 10 {

	// ! is the new line operator
	write i , ! 

} // Outputs the numbers between 1-10 (inclusive) on new lines

A while loop looks like this:

set x=1

while x<10 {
	write x, !
	set x = x+1
} 

// Outputs numbers 1-9 on new lines

If you want the loop to execute once before evaluating the expression, you can use do...while:

set x=1
do {
	write x, !
	set x=x+1
} while x<0

// Outputs 1, then loop ends

You can catch exceptions using try and catch operators. There are many methods to parse, print and handle errors in ObjectScript, with one included in the example below:

set newarray(1) = 1
try{
	write newarray(2)
}
catch{
	write "Code Errored - maybe we haven't defined newarray(2)", !
	write "The Error Message is "_$ZERROR,!
}

// Running this in a method would output:
// Code Errored - maybe we haven't defined newarray(2)
// The Error Message is <UNDEFINED>MethodName+3^packagename.ClassName.1 *newarray(2)