Quickstart guide to IRIS DB on Linux Systems

Introduction

This is a quickstart guide to IRIS for Linux systems administrators who need to be able to support the IRIS DB as well as other normal infrastructure tasks.

IRIS is a DB system from Intersystems. An IRIS DB can hold code (in the form of a Class) or data (in the form of Globals). IRIS DB are Linux files called IRIS.DAT.

IRIS was previously called Cache. There may be some references to Cache in the Intersystems documentation or forums or in some of your system documentation.

IRIS classes are coded in language call ObjectScript. IRIS classes have properties and methods.

IRIS classes can be run as interactive jobs or as scheduled tasks all within IRIS.

IRIS code can be in terms of a procedure.

IRIS DBs are typically journalled in case transactions need to be rolled back or DBs need to be recovered from a backup via a rolled forward process.

IRIS DBs can be mirrored to provide a level of redundancy across 2 servers. If DBs are mirrored then the transaction updates must be committed to both mirror members before the application is advised that the update is successful. Intersystems terms the mirror members as “failover members”. One of the failover members is termed the PRIMARY and the other member is termed BACKUP.

There is also an arbiter node(server) so that there is a quorum. Quorum members “vote” as to which failover member has failed.

There can be a asynchronous mirror node. The asynchronous mirror node is updated on a store and forward basis from journals.

IRIS DB has a product called Ensemble that supports productions. There can be only one production per name space. Ensemble can be used to develop applications using a concept of Services (input queues), Processes (how to process the input queue) and Operations (output queue).

IRIS DB has a product called JReports for developing reports. The development of reports is intended to be like Crystal reports.

Interacting with IRIS

You can connect to IRIS with:

iris session <instance name>

You can find out how many instances there are defined on your system:

iris list

You can also connect to IRIS via the Management Portal which is GUI/web based.

There is also a command like interface called WebTerminal which is often installed.

IRIS is configured via a configuration/parameter file typically called iris.cpf.

The iris.cpf file will show the location of the IRIS.DAT file for each defined database. The iris.cpf file will also show the mirror configuration.

Namespace vs DB

DB files by convention live in a directory that has the name of the DB itself.

Namespace are a logical concept that stores data or code.

A namespace provides access to data and to code, which is stored (typically) in multiple databases. Databases (IRIS.DAT) are the physical manifestation of the namespace.

All InterSystems IRIS systems will have a namespace of “%SYS” and “USER”. There are other default namespaces:

https://docs.intersystems.com/irislatest/csp/docbook/DocBook.UI.Page.cls?KEY=GORIENT_enviro#GORIENT_enviro_namespace_system

Journalling

Journal records are written to journal files which are located on one of 2 directories/filesystems – a primary and secondary area. When the primary area is full then journals will be written to the  secondary area. When the secondary area is full then journals will be written to the  primary area.  When the primary area is full then journals will be written to the  secondary area….

Journal files are switched when backups start, backups finish, under operator control or when the configured journal size is exceeded.

When both journal areas are full then all transactions stop.

There is usually a scheduled task that deletes old journal based on the age (number of days prior to today) or the number of previous backups. The default is 2 days old or 2 backups completed. 

Objectscript

These are some basic commands:

DO <- run a class method or procedure that is stored in the namespace/database

SET <- assign a value to a variable. Variable can be set to a literal or output from a method or class property. Variables do not need to be declared.

KILL <- deletes a variable

WRITE <- write text or variable contents or combination

Variable names are case-sensitive.

If the variable name starts with a ^ then it is a global. Global are multi dimensional storage areas. Where the variable is a global (variable name starting with ^) this structure is written persistently to the namespace then to the database(s).

Intersystems documentation says:

“In InterSystems IRIS, a database contains globals and nothing else; even code is stored in globals. 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.”

All other variables only exist in current user session.

If the name with DO  starts with a ^ then it is a procedure. For example

DO ^MIRROR

DO ^JOURNAL

ZN “%SYS” <- Change namespace

set status=##class(%SYS.Journal.System). GetState() <- Get the journal status

write $CASE(status,                                                          <- Print the journal status using a case statement

            0:"Enabled",1:"Disabled",2:"Suspended",

            3:"Frozen",4:"Paused")

List all namespaces

DO ##class(%SYS.Namespace).ListAll(.result)

zwrite result