This application is not supported by InterSystems Corporation. Use it at your own risk.

What's new in this version

Initial Open Source Release


A Ruby Extension for InterSystems Cache/IRIS and YottaDB.

Chris Munt
20 January 2021, M/Gateway Developments Ltd

  • Current Release: Version: 2.1; Revision 40a.
  • Two connectivity models to the InterSystems or YottaDB database are provided: High performance via the local database API or network based.
  • Release Notes can be found at the end of this document.



mg_ruby is an Open Source Ruby extension developed for InterSystems Cache/IRIS and the YottaDB database. It will also work with the GT.M database and other M-like databases.


Ruby installation:

InterSystems Cache/IRIS or YottaDB (or similar M database):

Installing mg_ruby

There are three parts to mg_ruby installation and configuration.

  • The Ruby extension (
  • The database (or server) side code: zmgsi
  • A network configuration to bind the former two elements together.

Building the mg_ruby extension

mg_ruby is written in standard C. For Linux systems, the Ruby installation procedure can use the freely available GNU C compiler (gcc) which can be installed as follows.


   apt-get install gcc

Red Hat and CentOS:

   yum install gcc

Apple OS X can use the freely available Xcode development environment.

Under Windows, Ruby is built with the Open Source MSYS2 Development kit and if you plan to build mg_ruby from the provided source code it is recommended that you select the pre-built 'Ruby+Devkit' option when downloading Ruby for Windows. This package will install Ruby together with all the tools needed to build mg_ruby.

Alternatively, there are pre-built Windows x64 binaries available from:

The pre-built module should be copied to the appropriate location in the Ruby file system. For example, using an 'out of the box' Ruby 2.7 installation this will be:


Having done this, mg_ruby is ready for use.

Building the source code

Having created a suitable development environment, the Ruby Extension installer can be used to build and deploy mg_ruby. You will find the setup scripts in the /src directory of the distribution.

UNIX and Windows using the MSYS2 Development Toolkit (most installations):

The commands listed below are run from a command shell. For Windows, the MSYS2 command shell provided with the 'Ruby+Devkit' distribution should be used. For example, with the 'out of the box' Ruby 2.7 installation this will be found at: C:\Ruby27-x64\msys64\msys2.

   ruby extconf.rb
   make install

Windows using the Microsoft Development Toolkit:

   ruby extconf.rb
   nmake install

Installing the M support routines

The M support routines are required for:

  • Network based access to databases.

Two M routines need to be installed (%zmgsi and %zmgsis). These can be found in the Service Integration Gateway (mgsi) GitHub source code repository ( Note that it is not necessary to install the whole Service Integration Gateway, just the two M routines held in that repository.

Installation for InterSystems Cache/IRIS

Log in to the %SYS Namespace and install the zmgsi routines held in /isc/

   do $system.OBJ.Load("/isc/","ck")

Change to your development Namespace and check the installation:

   do ^%zmgsi

   M/Gateway Developments Ltd - Service Integration Gateway
   Version: 3.6; Revision 15 (6 November 2020)

Installation for YottaDB

The instructions given here assume a standard 'out of the box' installation of YottaDB (version 1.30) deployed in the following location:


The primary default location for routines:


Copy all the routines (i.e. all files with an 'm' extension) held in the GitHub /yottadb directory to:


Change directory to the following location and start a YottaDB command shell:

   cd /usr/local/lib/yottadb/r130

Link all the zmgsi routines and check the installation:

   do ylink^%zmgsi

   do ^%zmgsi

   M/Gateway Developments Ltd - Service Integration Gateway
   Version: 3.6; Revision 15 (6 November 2020)

Note that the version of zmgsi is successfully displayed.

Setting up the network service (for network based connectivity only)

The default TCP server port for zmgsi is 7041. If you wish to use an alternative port then modify the following instructions accordingly.

Ruby code using the mg_ruby functions will, by default, expect the database server to be listening on port 7041 of the local server (localhost). However, mg_ruby provides the functionality to modify these default settings at run-time. It is not necessary for the Ruby installation to reside on the same host as the database server.

InterSystems Cache/IRIS

Start the Cache/IRIS-hosted concurrent TCP service in the Manager UCI:

   do start^%zmgsi(0) 

To use a server TCP port other than 7041, specify it in the start-up command (as opposed to using zero to indicate the default port of 7041).


Network connectivity to YottaDB is managed via the xinetd service. First create the following launch script (called zmgsi_ydb here):



   cd /usr/local/lib/yottadb/r130
   export ydb_dir=/root/.yottadb
   export ydb_dist=/usr/local/lib/yottadb/r130
   export ydb_routines="/root/.yottadb/r1.30_x86_64/o*(/root/.yottadb/r1.30_x86_64/r /root/.yottadb/r) /usr/local/lib/yottadb/r130/"
   export ydb_gbldir="/root/.yottadb/r1.30_x86_64/g/yottadb.gld"
   $ydb_dist/ydb -r xinetd^%zmgsis

Note that you should, if necessary, modify the permissions on this file so that it is executable. For example:

   chmod a=rx /usr/local/lib/yottadb/r130/zmgsi_ydb

Create the xinetd script (called zmgsi_xinetd here):



   service zmgsi_xinetd
        disable         = no
        type            = UNLISTED
        port            = 7041
        socket_type     = stream
        wait            = no
        user            = root
        server          = /usr/local/lib/yottadb/r130/zmgsi_ydb
  • Note: sample copies of zmgsi_xinetd and zmgsi_ydb are included in the /unix directory of the mgsi GitHub repository here.

Edit the services file:


Add the following line to this file:

   zmgsi_xinetd          7041/tcp                        # zmgsi

Finally restart the xinetd service:

   /etc/init.d/xinetd restart

Resources used by zmgsi

The zmgsi server-side code will write to the following global:

  • ^zmgsi: The event Log.

Using mg_ruby

Ruby programs may refer to, and load, the mg_ruby module using the following directive at the top of the script.

   require 'mg_ruby'
   mg_ruby =

Having added this line, all methods listed provided by the module can be invoked using the following syntax.


It is not necessary to name your instance as 'mg_ruby'. For example, you can have:

   require 'mg_ruby'
   <name> =

Then methods can be invoked as:


Connecting to the database

By default, mg_ruby will connect to the server over TCP - the default parameters for which being the database listening locally on port 7041. This can be modified using the following function.

   mg_ruby.m_set_host(<netname>, <port>, <username>, <password>)

The embedded default are for mg_ruby to connect to 'localhost' listening on TCP Port 7041.


   mg_ruby.m_set_host("localhost", 7041, "", "")

Connecting to the database via its API.

As an alternative to connecting to the database using TCP based connectivity, mg_ruby provides the option of high-performance embedded access to a local installation of the database via its API.

InterSystems Caché or IRIS.

Use the following functions to bind to the database API.

   mg_ruby.m_bind_server_api(<dbtype>, <path>, <username>, <password>, <envvars>, <params>)


  • namespace: Namespace.
  • dbtype: Database type ('Cache' or 'IRIS').
  • path: Path to database manager directory.
  • username: Database username.
  • password: Database password.
  • envvars: List of required environment variables.
  • params: Reserved for future use.


   result = mg_ruby.m_bind_server_api("IRIS", "/usr/iris20191/mgr", "_SYSTEM", "SYS", "", "")

The bind function will return '1' for success and '0' for failure.

Before leaving your Ruby application, it is good practice to gracefully release the binding to the database:



Use the following function to bind to the database API.

   mg_ruby.m_bind_server_api(<dbtype>, <path>, <username>, <password>, <envvars>, <params>)


  • dbtype: Database type (‘YottaDB’).
  • path: Path to the YottaDB installation/library.
  • username: Database username.
  • password: Database password.
  • envvars: List of required environment variables.
  • params: Reserved for future use.


This example assumes that the YottaDB installation is in: /usr/local/lib/yottadb/r130. This is where the library is found. Also, in this directory, as indicated in the environment variables, the YottaDB routine interface file resides ( in this example). The interface file must contain the following line:

   ifc_zmgsis: ydb_char_t * ifc^%zmgsis(I:ydb_char_t*, I:ydb_char_t *, I:ydb_char_t*)

Moving on to the Ruby code for binding to the YottaDB database. Modify the values of these environment variables in accordance with your own YottaDB installation. Note that each line is terminated with a linefeed character, with a double linefeed at the end of the list.

   envvars = "";
   envvars = envvars + "ydb_dir=/root/.yottadb\n"
   envvars = envvars + "ydb_rel=r1.30_x86_64\n"
   envvars = envvars + "ydb_gbldir=/root/.yottadb/r1.30_x86_64/g/yottadb.gld\n"
   envvars =envvars + "ydb_routines=/root/.yottadb/r1.30_x86_64/o*(/root/.yottadb/r1.30_x86_64/r root/.yottadb/r) /usr/local/lib/yottadb/r130/\n"
   envvars = envvars + "ydb_ci=/usr/local/lib/yottadb/r130/\n"
   envvars = envvars + "\n"

   result = mg_ruby.m_bind_server_api("YottaDB", "/usr/local/lib/yottadb/r130", "", "", envvars, "")

The bind function will return '1' for success and '0' for failure.

Before leaving your Ruby application, it is good practice to gracefully release the binding to the database:


Invocation of database commands

Before invoking database functionality, the following simple script can be used to check that mg_ruby is successfully installed.

   puts mg_ruby.m_ext_version()

This should return something like:

   M/Gateway Developments Ltd. - mg_ruby: Ruby Gateway to M - Version 2.1.40

Now consider the following database script:

   Set ^Person(1)="Chris Munt"
   Set name=$Get(^Person(1))

Equivalent Ruby code:

   mg_ruby.m_set("^Person", 1, "Chris Munt")
   name = mg_ruby.m_get("^Person", 1);

mg_ruby provides functions to invoke all database commands and functions.

Set a record

   result = mg_ruby.m_set(<global>, <key>, <data>)


   result = mg_ruby.m_set("^Person", 1, "Chris Munt")

Get a record

   result = mg_ruby.m_get(<global>, <key>)


   result = mg_ruby.m_get("^Person", 1)

Delete a record

   result = mg_ruby.m_delete(<global>, <key>)


   result = mg_ruby.m_delete("^Person", 1)

Check whether a record is defined

   result = mg_ruby.m_defined(<global>, <key>)


   result = mg_ruby.m_defined("^Person", 1)

Parse a set of records (in order)

   result = mg_ruby.m_order(<global>, <key>)


   key = ""
   while ((key = mg_ruby.m_order("^Person", key)) != "")
      puts key + " = " + mg_ruby.m_get("^Person", key)

Parse a set of records (in reverse order)

   result = mg_ruby.m_previous(<global>, <key>)


   key = ""
   while ((key = mg_ruby.m_previous("^Person", "")) != "")
      puts key + " = " + mg_ruby.m_get("^Person", key)

Invocation of database functions

   result = mg_ruby.m_function(<function>, <parameters>)


M routine called 'math':

   add(a, b) ; Add two numbers together
             quit (a+b)

Ruby invocation:

  result = mg_ruby.m_function("add^math", 2, 3);

Direct access to InterSystems classes (IRIS and Cache)

Invocation of a ClassMethod

   result = mg_ruby.m_classmethod(<class_name>, <classmethod_name>, <parameters>);

Example (Encode a date to internal storage format):

    result = mg_ruby.m_classmethod("%Library.Date", "DisplayToLogical", "10/10/2019");


Copyright (c) 2018-2021 M/Gateway Developments Ltd, Surrey UK.
All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Release Notes

v2.1.40 (23 January 2020)

  • Initial Release

v2.1.40a (20 January 2021)

  • Restructure and update the documentation.
0 (0)
Developer Environment
Works with
CachéEnsembleInterSystems IRISInterSystems IRIS for Health
Last updated