Introduction to ObjectScript

Features

Some of the key features of ObjectScript include:

• Native support for objects including methods, properties, and polymorphism

• Support for concurrency control

• A set of commands for dealing with I/O devices

• Support for multidimensional, sparse arrays: both local and global (persistent)

• Support for efficient, Embedded SQL

• Support for indirection as well as runtime evaluation and execution of commands

Sample Class with ObjectScript

Class definitions are not part of ObjectScript, but can include ObjectScript in multiple places, and classes are compiled into routines and ultimately into the same runtime code. The most common use for ObjectScript in a class is within methods.

The following shows an sample class that gives us an opportunity to see some common ObjectScript commands, operators, and functions, and to see how code is organized within a method.

Class User.DemoClass
{

/// Generate a random number.
/// This method can be called from outside the class.
ClassMethod Random() [ Language = objectscript ]
{
    set rand=$RANDOM(10)+1        ; rand is an integer in the range 1-10
    write "Your random number: "_rand
    set name=..GetNumberName(rand)
    write !, "Name of this number: "_name
}

/// Input a number.
/// This method can be called from outside the class.
ClassMethod Input() [ Language = objectscript ]
{
    read "Enter a number from 1 to 10: ", input
    set name=..GetNumberName(input)
    write !, "Name of this number: "_name
}

/// Given an number, return the name.
/// This method can be called only from within this class.
ClassMethod GetNumberName(number As %Integer) As %Integer [ Language = objectscript, Private ]
{
    set name=$CASE(number,1:"one",2:"two",3:"three",
        4:"four",5:"five",6:"six",7:"seven",8:"eight",
        9:"nine",10:"ten",:"other")
    quit name
}

/// Write some interesting values.
/// This method can be called from outside the class.
ClassMethod Interesting() [ Language = objectscript ]
{
    write "Today's date: "_$ZDATE($HOROLOG,3)
    write !,"Your installed version: "_$ZVERSION
    write !,"Your username: "_$USERNAME
    write !,"Your security roles: "_$ROLES
}

}

Note the following highlights:

• The Random() and Input() methods invoke the GetNumberName() method, which is private to this class and cannot be called from outside the class.

• WRITE, QUIT, SET, and READ are ObjectScript commands. The language includes other commands to remove variables, commands to control program flow, commands to control I/O devices, commands to manage transactions (possibly nested), and so on.

  The names of commands are not case-sensitive, although they are shown in running text in all upper case by convention.

• The sample includes two ObjectScript operators. The plus sign (+) performs addition, and the underscore (_) performs string concatenation.

  ObjectScript provides the usual operators and some special operators not seen in other languages.

• $RANDOM, $CASE, and $ZDATE are ObjectScript functions.

  The language provides functions for string operations, conversions of many kinds, formatting operations, mathematical operations, and others.

• $HOROLOG, $ZVERSION, $USERNAME, and $ROLES are ObjectScript system variables (called special variables in InterSystems IRIS). Most special variables contain values for aspects of the InterSystems IRIS operating environment, the current processing state, and so on.

• ObjectScript supports comment lines, block comments, and comments at the end of statements.

We can execute the methods of this class in the ObjectScript shell, as a demonstration. In these examples, TESTNAMESPACE> is the prompt shown in the shell. The text after the prompt on the same line is the entered command. The lines after that show the values that the system writes to the shell in response.

TESTNAMESPACE>do ##class(User.DemoClass).Input()
Enter a number from 1 to 10: 7
Name of this number: seven
TESTNAMESPACE>do ##class(User.DemoClass).Interesting()
Today's date: 2021-07-15
Your installed version: IRIS for Windows (x86-64) 2019.3 (Build 310U) Mon Oct 21 2019 13:48:58 EDT
Your username: SuperUser
Your security roles: %All
TESTNAMESPACE>

Sample Routine

The following shows an sample routine named demoroutine that is written in ObjectScript. It contains procedures that do the exact same thing as the methods shown in the sample class in the previous section.

 ; this is demoroutine 
 write "Use one of the following entry points:"
 write !,"random"
 write !,"input"
 write !,"interesting"
 quit 
 
 //this procedure can be called from outside the routine
random() public {
    set rand=$RANDOM(10)+1        ; rand is an integer in the range 1-10
    write "Your random number: "_rand
    set name=$$getnumbername(rand)
    write !, "Name of this number: "_name
 }

 //this procedure can be called from outside the routine
input() public {
    read "Enter a number from 1 to 10: ", input
    set name=$$getnumbername(input)
    write !, "Name of this number: "_name
 }
 
 //this procedure can be called only from within this routine
getnumbername(number) {
    set name=$CASE(number,1:"one",2:"two",3:"three",
        4:"four",5:"five",6:"six",7:"seven",8:"eight",
        9:"nine",10:"ten",:"other")
    quit name
}

 /* write some interesting values
 this procedure can be called from outside the routine
 */
interesting() public {
    write "Today's date: "_$ZDATE($HOROLOG,3)
    write !,"Your installed version: "_$ZVERSION
    write !,"Your username: "_$USERNAME
    write !,"Your security roles: "_$ROLES  
    }

Note the following highlights:

• The only identifiers that actually start with a caret (^) are the names of globals; these are discussed later in this page. However, in running text and in code comments, it is customary to refer to a routine as if its name started with a caret, because you use the caret when you invoke the routine (as shown later in this page). For example, the routine demoroutine is usually called ^demoroutine.

• The routine name does not have to be included within the routine. However, many programmers include the routine name as a comment at the start of the routine or as the first label in the routine.

• The routine has multiple labels: random, input, getnumbername, and interesting.

  Labels are used to indicate the starting point for procedures (as in this example), functions, and subroutines. You can also use them as a destination for certain commands.

  Labels are common in routines, but you can also use them within methods.

  Labels are also called entry points or tags.

• The random and input subroutines invoke the getnumbername subroutine, which is private to the routine.

We can execute parts of this routine in the ObjectScript shell, as a demonstration. First, the following shows a session in which we run the routine itself.

TESTNAMESPACE>do ^demoroutine
Use one of the following entry points:
random
input
TESTNAMESPACE>

When we run the routine, we just get help information, as you can see. It is not required to write your routines in this way, but it is common. Note that the routine includes a QUIT before the first label, to ensure that when a user invokes the routine, processing is halted before that label. This practice is also not required, but is also common.

Next, the following shows how a couple of the subroutines behave:

TESTNAMESPACE>do input^demoroutine
Enter a number from 1 to 10: 7
Name of this number: seven
TESTNAMESPACE>do interesting^demoroutine
Today's date: 2018-02-06
Your installed version: IRIS for Windows (x86-64) 2018.1 (Build 513U) Fri Jan 26 2018 18:35:11 EST
Your username: _SYSTEM
Your security roles: %All
TESTNAMESPACE>

A method can contain the same statements, labels, and comments as routines do. That is, all the information here about the contents of a routine also applies to the contents of a method.

Language Overview

ObjectScript does not define any reserved words: you are free to use any word as an identifier (such as a variable name). In order to accomplish this, ObjectScript uses a set of built-in commands as well as special characters (such as the “$” prefix for function names) in order to distinguish identifiers from other language elements.

For example, to assign a value to a variable, you can use the SET command:

 SET x = 100
 WRITE x

In ObjectScript it is possible (though not recommended) to use any valid name as an identifier name, as shown in the following program, which is functionally identical to the previous example:

 SET SET = 100
 WRITE SET

Some components of ObjectScript, such as command names and function names, are not case-sensitive. Other components of ObjectScript, such as variable names, labels, class names and method names are case-sensitive. For details, see Case Sensitivity.

You can insert or omit whitespace almost anywhere in ObjectScript. However, two uses of whitespace are significant:

1. A command and its arguments must be separated by at least one space.

2. Each command line must be indented by at least one space. A command cannot start or continue on the first character position of a line.

Comments must also be indented. Some other syntaxes, such as macro preprocessor statements, can begin on the first character position of a line. For details, see Whitespace.

ObjectScript does not use a command terminator character or a line terminator character.

Statements and Commands

An ObjectScript program consists of a number of statements. Each statement defines a specific action for a program to undertake. Each statement consists of a command and its arguments.

Consider the following ObjectScript statement:

 SET x="World"
 WRITE "Hello",!,x

WRITE is a command. This example uses three arguments for the command: the literal string “Hello”; the “!” character, which is a symbolic operator specific to the WRITE command that issues a line feed/carriage return; and the local variable x, which is replaced during execution by its current value. Arguments are separated by commas; you may also add whitespace between arguments (with some restrictions). For information on whitespace, see Syntax.

Most ObjectScript commands (and many functions and special variables) have a long form and a short (abbreviated) form (typically one or two characters). For example, the following program is identical to the previous one, but uses the abbreviated command names:

 S x="World"
 W "Hello",!,x

Older code commonly used the short forms (see Abbreviations Used in ObjectScript). For clarity, it is best to use the long forms.

For more information on commands, see Commands or the individual reference page within the ObjectScript Reference.

Functions

A function is code that performs an operation (for example, converting a string to its equivalent ASCII code values) and returns a value. A function is invoked within a command line. This invocation supplies parameter values to the function, which uses these parameter values to perform some operation. The function then returns a single value (the result) to the invoking command. You can use a function any place you can use an expression.

InterSystems IRIS provides a large number of system-supplied functions (sometimes known as “intrinsic” functions), which you cannot modify. These functions are identifiable, as they always begin with a single dollar sign (“$”) and enclose their parameters within parentheses; even when no parameters are specified, the enclosing parentheses are mandatory. (Special variable names also begin with a single dollar sign, but they do not have parentheses.)

Many system-supplied function names have abbreviations. In the text of this manual, the full function names are used. The abbreviation is shown on the function’s reference page and a complete list is provided in Abbreviations Used in ObjectScript.

A function always returns a value. Commonly, this return value is supplied to a command, such as SET namelen=$LENGTH("Fred Flintstone") or WRITE $LENGTH("Fred Flintstone"), or to another function, such as WRITE $LENGTH($PIECE("Flintstone^Fred","^",1)). Failing to provide a recipient for the return value usually results in a <SYNTAX> error. However, in a few functions, providing a recipient for the return value is not required. An operation performed by executing the function or the setting of one of the function’s parameters is the relevant operation. In these cases, you can invoke a function without receiving its return value by using the DO or JOB command. For example, DO $CLASSMETHOD(clname,clmethodname,singlearg).

A function can have no parameters, a single parameter, or multiple parameters. Function parameters are positional and separated by commas. Many parameters are optional. If you omit a parameter, InterSystems IRIS uses that parameter’s default. Because parameters are positional, you commonly cannot omit a parameter within a list of specified parameters. In some cases (such as $LISTTOSTRING) you can omit a parameter within a parameter list and supply a placeholder comma. You do not have to supply placeholder commas for optional parameters to the right of the last specified parameter.

For most functions, you cannot specify multiple instances of the same parameter. The exceptions are $CASE, $CHAR, and $SELECT.

Commonly, a parameter can be specified as a literal, a variable, or the return value of another function. In a few cases, a parameter must be supplied as a literal. In most cases, a variable must be defined before it can be specified as a function parameter, or an <UNDEFINED> error is generated. In a few cases (such as $DATA) the parameter variable does not have to be defined.

Commonly, function parameters are input parameters that supply a value to the function. In a few cases, a function both returns a value and sets an output parameter. For example, $LISTDATA returns a boolean value indicating whether there is a list element at the specified position; it also sets its third parameter (if included in the parameter list) equal to the value of that list element.

All functions can be specified on the right side of a SET command (for example, SET x=$LENGTH(y)). A few functions can also be specified on the left side of a SET command (for example, SET $LIST(list,position,end)=x). Functions that can be specified on the left side of a SET are identified as such in their reference page syntax block.

System-supplied functions are provided as part of InterSystems IRIS. The ObjectScript Language Reference describes each of the system-supplied functions. A function provided in a class is known as a method. Methods provided in InterSystems IRIS are described in the InterSystems Class Reference.

In addition to its system-supplied functions, ObjectScript also supports user-defined functions (sometimes known as “extrinsic” functions). See Defining Procedures.

Expressions

An expression is any set of tokens that can be evaluated to yield a single value. For example, the literal string, “hello”, is an expression. So is l + 2. Variables such as x, functions such as $LENGTH, and special variables such as $ZVERSION also evaluate to an expression.

Within a program, you use expressions as arguments for commands and functions:

 SET x = "Hello"
 WRITE x,!
 WRITE 1 + 2,!
 WRITE $LENGTH(x),!
 WRITE $ZVERSION

Variables

In ObjectScript, a variable is the name of a location in which a runtime value can be stored. Variables must be defined, for example, by using the SET command.

Variables in ObjectScript are untyped; that is, they do not have an assigned data type and can legally take any data value. No syntax error occurs when you assign a string value to a variable that previously held a numeric value, or vice versa. (Syntax errors do occur, however, if you attempt to use a variable inappropriately, such as if you try to set an object property when the variable does not contain an instance of an object, or when you pass a non-list value to a function that requires a list, and so on. That is, many ObjectScript functions expect specific kinds of input.)

ObjectScript supports several kinds of variables, characterized by differing scopes and features:

• Local variables — A variable that is accessible only by the InterSystems IRIS process that created it, and which is automatically deleted when the process terminates.

• Globals — A persistent variable that is stored within the InterSystems IRIS database. A global is accessible from any process, and persists after the process that created it terminates.

• Process-private globals — A variable that is accessible only by the InterSystems IRIS process and is deleted when the process ends. Process-private globals are especially useful for temporary storage of large data values.

• Special variables (also known as system variables) — One of a special set of built-in variables that contain a value for a particular aspect of the InterSystems IRIS operating environment. All special variables always have values. Some special variables can be set by the user, others can only be set by InterSystems IRIS. Special variables are not array variables.

• Object properties — A value associated with, and stored within, a specific instance of an object.

Local, global, and process-private globals can all be multidimensional arrays.

See Variables and Process-Private Globals.

Operators

ObjectScript defines a number of built-in operators. These include arithmetic operators, logical operators, and pattern match operators. For an overview, see Operators.

See Also

To learn more about ObjectScript, you can also refer to:

• The ObjectScript Tutorial for an interactive introduction to most language elements.

• The ObjectScript Reference for details on individual commands and functions.