IBM I Toolkit For Ruby – iit For Short

by | Nov 22, 2017

Originally published: IT Jungle on 4/7/15

What if I told you that the best developers in the world are available to work on your next project? What if I told you that they will work for free? Well, they are and they will. In the following paragraphs, I tell you why and how.

The best developers in the world will help you with your projects, for free, because of the magic of open source. Open source efforts have to rank right up there on the list of abnormalities of the human race. Why? Because so much is given away at high cost (time, which in turn is often money). It makes one scratch their head as to why it has become so prolific. Watch this video. It will tell you–in a very entertaining way–more about what motivates open source developers.

I suppose each person has their own reason(s) for contributing. I equate it to how I might go and ask my neighbor for a cup of sugar because I am out and don’t have time to run to the store. In that scenario my neighbor was able to help me and maybe it gave them a slice of life purpose. In short, community has happened. The other important reality is we are greater than the sum of our parts. My development team and I can only produce so much in a workday, and more than likely somebody else is going through the same motions of development. If we combine our efforts, we can get an end solution quicker and most likely a more robust and honed solution for multiple purposes or industries.

It is for these reasons I am introducing a new open source project named iit, short for “IBM i Toolkit”. The iit project is meant to give Ruby developers simple and easy access to existing IBM i resources. The code was born out of needs we had at KrengelTech and we believe others could make use of iit, and even more importantly we are hoping others will contribute. That’s what this article is about: how to contribute to an open source project.

These are the high-level steps you need to take to contribute to the iit project:

  • Fork the iit Bitbucket project into your own Bitbucket account.
  • Use PASE Git client to “clone” the iit project source to the IFS.
  • Build and install iit as a RubyGem on your IBM i.
  • Author and test your new feature in the iit code base.
  • Use Git commands to add, commit, and push the code change back to your Bitbucket.
  • Issue a Pull Request to contribute back the new feature that was authored.

The first skills you need to learn are how to fork a project and how to generate pull requests. At KrengelTech, we use Bitbucket to carry out these processes because we get unlimited private repositories, and because Bitbucket integrates with a number of other tools that are very useful to an IT development team, including:

Bitbucket has some good documentation here, so I won’t delve too deep as to the definition but instead describe why it is necessary for the iit project.

Right now only a few people have write access to the iit Bitbucket git repository, but we still want to make it easy for others to contribute to the project.

Let’s pretend for a moment that I am not allowed to commit changes to the iit git repo, yet I desire to add a new feature to retrieve IBM i system values (i.e. DSPSYSVAL). To do this I need to fork the existing iit repo, as shown below, which makes a copy of the entire repo under my profile. This repo is completely separate from the original iit repo.

NOTE: You will need to sign up for a free Bitbucket account before you can fork.

Forking the existing iit repo.

Forking the existing iit repo.

Next you will be prompted to supply additional information. I only changed the Description field.

Editing the description of the new fork.

Editing the description of the new fork.

Once the fork is complete you will now have a git repo named iit under your personal profile, as shown below.

Forked repo under the author's personal profile.

Forked repo under the author’s personal profile.

At this point the code is only on the server and we now need to “clone” it down to the IFS on our IBM i. If you look to the far right of the project page you can see the field that holds the path to the repository. Copy that value and use it on the next step.

Path to locally clone the forked repo.

Path to locally clone the forked repo.

Open up a shell (either through ssh or CALL QP2TERM) and run the following commands, making sure to supply your profile and Bitbucket repo.

Now go into the newly created project directory.

Being that this is a RubyGem we need to first build and install it. This will allow us to test the existing functionality in the next step.

Now it is time to write the new feature of obtaining a system value. I plan on parsing the DSPSYSVAL output with regular expressions (regex for short), but first I need to get an idea of what the output looks like. Below I’ve started up an irb session, required iit gem, and run the existing IIT.qcmdexc command.

The portion immediately following => is the output from the command and what we need to parse with a regex. I am far from a regex expert so I head over to http://regex101.com, which is a tool that lets me interactively enter regex syntax to test my selection. Below is a screenshot of what the regex matcher looks like and the regex expression I used.

Regex expression selecting the QMODEL value.

Regex expression selecting the QMODEL value.

I use regex infrequently enough that I have to reach out for help. The cool thing about regex101.com is they have an IRC (instant chat) page where you can ask questions including posting a URL where your current string and regex isn’t working. Below is the conversation I had on IRC. Note that my question was answered within two minutes. Nice!

Live community support in IRC.

Live community support in IRC.

Now we are ready to introduce that regex into a new Ruby method named DSPSYSVAL to file lib/iit.rb, as shown below. The second line of the method starts out with the regex, then calls the “match” method on the regex passing the result from the call to “qcmdexc”. The “rescue” at the end is in case something blows up, then it will simply return blanks.

Now that the method is written we need test it. We can do that by first building and then installing the Gem, as shown below.

Next start an irb session and invoke the new method, as shown below.

It worked! The next step, if I am a responsible programmer, is to create a unit test for this new method. I will definitely do that but we won’t digress through it here for the sake of brevity and will instead cover that in another article.

At this point I have new code I need to put back into my Bitbucket so I can subsequently issue what’s called a “Pull Request” (PR for short). A PR is basically the process of me offering my changes back to the parent repository. First things first, let’s commit and add our changes. I always issue a “git status” to learn what’s changed in my repo, as shown below. As expected there are two modified files.

Next I use command “git add”, “git commit”, and “git push” to log an instance of this code in time and place it back on Bitbucket in my forked repo. Note the “.” (period) used on the “git add” command is signifying that all changes from the current directory on down should be added.

If you go back to your repo in the browser you can see the new commit, as shown below.

Our new commit in the browser.

Our new commit in the browser.

Next create a pull request so the parent repo knows we are done with the feature and would like to share, as shown below.

Creating a pull request.

Creating a pull request.

In the below screenshot we see the “from” and “to” repos. The title of the pull request is pre-filled with the most recent commit message and all that’s left to do is select Create pull request.

"From" our repo "to" the parent repo.

“From” our repo “to” the parent repo.

Now if I go back to the parent repo I can see the pull request and have the opportunity to review and merge it, as shown below.

Reviewing and merging the pull request.

Reviewing and merging the pull request.

If I am curious as to what changed in a particular file I can easily see it with the visually colorful diff tooling, as shown below.

Our additions are highlighted in green.

Our additions are highlighted in green.

I hope this gives you a better understanding on how to participate in the community. I would greatly appreciate if others would contribute to this project, even if it is a simple edit to the README.md file to give more examples of basic usage.

Stay tuned for an article on how to add unit tests to your Ruby code.

RPG-XML Suite

  • Call web APIs from RPG
  • Process XML and JSON
  • Offer web services

Litmis Spaces

Affordable IBM i cloud hosting

CyberSource Toolkit for i

  • Process credit cards from native RPG
  • Integrate CyberSource payment services

Follow Us

We can help you with all of your Git and Ruby needs! Contact us below.

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

Get Social

Share to your favorite social platform