Trying on a Ruby Ring

by | Aug 24, 2017

Originally published: MCPress Online on 2/05/2015
Updated author notes: This article includes reference to the ruby-itoolkit tool which is now open source and hosted on Bitbucket.

In the fall of 2013, PowerRuby became a formal port of the Ruby language and Rails web framework for IBM i, and in the spring of 2014, David Shirey introduced you to Ruby, giving an overview of history and comparison with other languages. This article will build on that foundation and dive into some tangible things you can try on your IBM i as a means to, as they say, “kick the tires”—or maybe better stated: let’s try on this Ruby ring and see how it fits.

If you haven’t already, head over to to download and install the free port of Ruby. If you’re unable to install PowerRuby, another option is to sign up for a free Cloud9 account, a browser-based IDE where you can do all of your Ruby work.

The first thing I will introduce is the InteractiveRuby Shell, or irb for short. This environment runs from a PASE shell and allows the entering of source code that is invoked and provides an immediate response, what the programming community calls a read-eval-print loop (REPL). You can start a PASE shell session using CALL QP2TERM, but I would instead highly recommend you ssh in from your laptop with a better client, like this Chrome plugin.



Below are a few lines of Ruby code to paste into the irb session. This is some procedural Ruby code that first defines a method named say_hi and subsequently invokes it. A Ruby method is similar to a subprocedure in RPG.

Figure 1 below show what it looks like to copy and paste into irb. The things entered in this irb session remain defined until you type quit. This means I can call say_hi a second time with a different name.

In the irb session, define a method and invoke it.

In the irb session, define a method and invoke it.

An important consideration in adopting any new language is its ability to call upon your existing investment in IBM i and RPG. That’s where a RubyGem named xmlservice comes into play. A RubyGem (Gem for short) is a collection of code that focuses on accomplishing a specific task. In the following scenario, the Gem’s purpose is to invoke an RPG program from the Ruby language. This Gem is jointly maintained by IBM and the team, which I’m on.

Below is a simple RPG program that has two parameters passed by reference. Note I am using 100% free-form RPG. This is not the RPG of your grandfather. Compile the below RPG into an object named PGM1.

The code below is the Ruby code necessary to invoke the above RPG program. The require statements are similar to /copy in RPG; they bring in outside functionality. The next portion is a qualified method call that will establish a connection to DB2 for i. Note that you need to modify the schema (aka library), username, and password values. Also note that this can be pasted into irb for quick and easy testing.

The code then defines the pgm1 variable with both the parameter list definition and values for the call to PGM1. Line is doing the actual invocation of RPG. Behind the scenes, a call to a generic DB2 stored procedure is made, and that in turn invokes MYLIB/PGM1. When control returns to the Ruby program, the results are now stored in the pgm1 Ruby variable and can be accessed with the syntax pgm1.response.mychar1, as shown. The puts method stands for “put string” and will output the resulting value to the screen.

Well, how did the Ruby ring fit? Obviously, there’s a certain amount of new syntax to learn, but I hope this gives you an idea of how simple it is to embrace Ruby. If you have questions or issues, please feel free to comment below or go to my bio to get my email. If you have questions specific to the xmlservice Gem, please direct them to the formal Bitbucket repository.


Easy web service API integration from RPG

Learn More

CyberSource Toolkit for i

Process credit cards from RPG

Learn More

Follow Us

Need Ruby to talk to RPG? We can help. Contact us below.

  • This field is for validation purposes and should be left unchanged.

Get Social

Share to your favorite social platform