docs.intersystems.com
Home  /  Application Development: Core Topics  /  Orientation Guide for Server-Side Programming  /  Introduction to InterSystems IRIS Programming


Orientation Guide for Server-Side Programming
Introduction to InterSystems IRIS Programming
[Back]  [Next] 
InterSystems: The power behind what matters   
Search:  


This book is an orientation guide for programmers. It is not a tutorial but rather a survey of the basic features of server-side programming.
This chapter provides a high-level overview of the language elements you can use in InterSystems IRIS™ server-side programs. It discusses the following topics:
Introduction
InterSystems IRIS is a high-performance object database with a built-in general-purpose programming language. It supports multiple processes and provides concurrency control. Each process has direct, efficient access to the data.
In InterSystems IRIS, you can write routines, classes, or a mix of these, as suits your preferences. In all cases, stored data is ultimately contained in structures known as globals (a later section in this chapter discusses these). InterSystems IRIS programming has the following features:
You can choose the approach that is appropriate for your needs.
Routines
When you create routines in InterSystems IRIS, you use ObjectScript. The following shows part of a routine written in ObjectScript:
    SET text = ""
    FOR i=1:5:$LISTLENGTH(attrs)
    {
        IF ($ZCONVERT($LIST(attrs, (i + 1)), "U") = "XREFLABEL")
        {
            SET text = $LIST(attrs, (i + 4))
            QUIT
        }
    }
    
    IF (text = "")
    {
        QUIT $$$ERROR($$$GeneralError,$$$T("Missing xreflabel value"))
    }
The next chapter provides an introduction to ObjectScript.
Classes
InterSystems IRIS also supports classes. You can use the system classes and you can define your own classes.
In InterSystems IRIS, a class can include familiar class elements such as properties, methods, and parameters (known as constants in other class languages). It can also include items not usually defined in classes, including triggers, queries, and indices.
The following shows a class definition:
Class Sample.Employee Extends Person
{

/// The employee's job title.
Property Title As %String(MAXLEN = 50);

/// The employee's current salary.
Property Salary As %Integer(MAXVAL = 100000, MINVAL = 0);

/// A character stream containing notes about this employee.
Property Notes As %Stream.GlobalCharacter;

/// A picture of the employee
Property Picture As %Stream.GlobalBinary;

/// This method overrides the method in the Person class.
Method PrintPerson() 
{
    Write !,"Name: ", ..Name, ?30, "Title: ", ..Title
    Quit
}

}
You can use classes from within routines. For example, the following shows part of a routine, in which we refer to the Sample.Person class:
 //get details of requested person; print them
showperson() public {
    set rand=$RANDOM(10)+1        ; rand is an integer in the range 1-10
    write "Your random number: "_rand
    set person=##class(Sample.Person).%OpenId(rand)  
    write !,"This person's name: "_person.Name
    write !,"This person's age: "_person.Age
    write !,"This person's home city: "_person.Home.City
      
    }
Similarly, a method can invoke a label in a routine. For example:
Method DemoRoutineCall(input) as %String
{
    Set value=$$function^myroutine(input)
    Quit value
}
Later chapters discuss classes in InterSystems IRIS and the unique capabilities of persistent classes in InterSystems IRIS.
Introduction to Globals
InterSystems IRIS supports a special kind of variable that is not seen in other programming languages; this is a global variable, which is usually just called a global. In InterSystems IRIS, the term global indicates that this data is available to all processes accessing this database. This usage is different from other programming languages in which global means “available to all code in this module.”
The contents of a global are stored in an InterSystems IRIS database. The next chapter introduces these more thoroughly; for now, it is important just to know the following points:
Ways to Access Data
In InterSystems IRIS, a database contains globals and nothing else; even code is stored in globals, as described later in this book. At the lowest level, all access to data is done via direct global access — that is, by using commands and functions that work directly with globals.
When you use persistent classes, discussed later in this book, you can create, modify, and delete stored data in either of the following ways:
Internally, the system always uses direct global access.
InterSystems SQL
InterSystems IRIS provides an implementation of SQL, known as InterSystems SQL.
You can use InterSystems SQL within routines and within methods. To use SQL in these contexts, you can use either or both of the following tools:
Macros
ObjectScript also supports macros, which define substitutions. The definition can either be a value, an entire line of code, or (with the ##Continue directive) multiple lines. You use macros to ensure consistency. For example:
 #define StringMacro "Hello, World!"

 write $$$StringMacro
To give you an idea of what can be done in macros, the following example shows the definition of a macro that is used internally:
 #define output1(%str,%lf,%indent) do output^%fm2class(%str,%lf,%indent,$$$display) 
This macro accepts an argument, as many of them do. It also refers to another macro.
You can use macros in routines as well as in classes. Some of the system classes use them extensively.
Include Files
You can define macros in a routine and use them later in the same routine. More commonly, you define them in a central place. To do this, you create and use include files. An include file defines macros and can include other include files.
The following shows parts of a system include file:
/// Create a success %Status code
#define OK                     1
 
/// Return true if the %Status code is success, and false otherwise
/// %sc - %Status code
#define ISOK(%sc)              (+%sc)
 
/// Return true if the %Status code if an error, and false otherwise
/// %sc - %Status code
#define ISERR(%sc)             ('%sc)
Then you can do the following:
Note that you use slightly different syntax to include an include file within a class definition. See Macros and Include Files in Class Definitions,” later in this book.
How These Code Elements Work Together
It is useful to understand how InterSystems IRIS uses the code elements introduced in this chapter.
The reason that you can use a mix of ObjectScript, InterSystems SQL, macros, class definitions, routines, and so on is that InterSystems IRIS does not directly use the code that you write. Instead, when you compile your code, the system generates the code that it uses, which is OBJ code, used by the InterSystems IRIS virtual machine.
There are multiple steps. It is not necessary to know the steps in detail, but the following points are good to remember:
Note:
All routines and class definitions are stored in the same InterSystems IRIS databases as the generated code. This fact makes the code easier to manage. InterSystems IRIS provides a robust set of source control hooks that InterSystems developers have used for many years. You can use these hooks as well.