ILEastic ... can it get even easier?

ILEastic is a microservice framework written mostly in C and available as an ILE service program. That means we can build web service in ILE languages like RPG and COBOL (and C of course). No more jumping through hoops to offer a web service to your colleagues or business partners.

Easier ?

Of course we can do/make it easier :) . Because getting ILEastic onto your server has been a pain so far for anyone not familiar with the various projects (namely ILEastic, noxDB and ILEfastCGI) and the tools used for building the projects. Offering a simple save file has not been very easy so far because your system may have a different CCSID as the one used for building the projects which may lead to incompatibilites.

But now I can offer you a nice RPM package which can be installed with iPKG. To install ILEastic with iPKG we just need the iPKG client on our machine (available here) and execute the install command.

ipkg install ileastic

But before we can execute this command we need to tell iPKG where it can get the RPM packages from. This can be done with a simple command:

ipkg addrepo 'RPGNextGen https://repo.rpgnextgen.com/repository'

This will create the necessary environment for iPKG. By default it will use the library IPKG but you can change that by adding the parameter IPKGLIB(YOUR_LIB).

After telling iPKG where it can find packages we need to tell it which packages can be found at the repository we configured. For this we just need another simple command:

ipkg update

Coming back to our original intent of installing ILEastic with the command:

ipkg install ileastic

Hmmm … it failed … and that is the correct result. Because ILEastic depends on noxDB we need to install noxDB before installing ILEastic (anybody remembering the old days of rpm where you manually needed to install every required package before installing the package you originally wanted to install?!). Automatically installing all dependencies is definitely on my list but needs much work and won’t be available in the near future. So here we go with first installing noxDB:

ipkg install noxdb2

Now we can install ILEastic (see the install command above).

Note that we don’t need to install the noxdb2-devel package. That is the beauty of these packages. You just install what you need. For ILEastic itself we don’t need the prototypes of noxDB. If you want to work with noxDB then of course you can install the noxDB prototypes.

But as we want to use the ILEastic procedures we will need the ILEastic prototypes which are available in the ileastic-devel package. So we are going to install that one too.

ipkg install 'ileastic-devel'

iPKG is not a global package manager. It works more like NPM where packages are managed on a per project base (per library in our case). To make a package installation only for a single user you just need to specify a separate library on the commands. To have ILEastic installed in my own library and home directory I would call the following commands:

ipkg addrepo 'RPGNextGen https://repo.rpgnextgen.com/repository' ipkglib(MIHAEL)
ipkg update ipkglib(MIHAEL)
ipkg install ileastic ipkglib(MIHAEL)
ipkg install 'ileastic-devel' ipkglib(MIHAEL) loc('/home/mihael/include')

We can see which packages have been installed by executing a simple command:

ipkg list installed

It will display the installed packages and their version.

ileastic (2.0.0)
ileastic-devel (2.0.0)
noxdb2 (2.0.0)

If you want to know more about iPKG take a look at the project wiki and this and this blog post.

And now … how about writing a little web service?!

First Web Service

Starting situation:

• noxDB and ILEastic is installed in library MIHAEL (by using iPKG)
• NOXDB2 and ILEASTIC service programs are registered in the binding directory MIHAEL/IPKG (automatically done by iPKG)
• ILEastic prototypes are installed and located at/home/mihael/include/ileastic/ileastic.rpgle (by using iPKG)
• library MIHAEL is part of the library list

Code

We are now set for creating our first RPG web service program with the new ILEastic installation. It will be a FREE RPG program (though we can also use it in a non FREE RPG program but it has to be an ILE program). So our program starts with

**FREE

For this little example we compile it in one go with the command CRTBNDRPG so we can add some compile options in the code (for production I would go with the two step approach of first creating a module with CRTRPGMOD and then creating the program with CRTPGM).

ctl-opt dftactgrp(*no) actgrp(*caller) bnddir('IPKG') thread(*concurrent);

Note: The option thread(*concurrent) is very important because ILEastic is a multi-threaded framework and all our web service programs and service programs are running in the same job but in multiple threads. This compile option makes sure the threads are not tripping on each others toes when it comes to resource and memory management.

Next we need to include the ILEastic prototypes.

/include '/home/mihael/include/ileastic/ileastic.rpgle'

I like to directly jump into a procedure at program start without forfeiting the default error handler.

main();
*inlr = *on;

And here is our main procedure where we setup the web service and configure our end points / routes.

dcl-proc main;
  dcl-ds config likeds(il_config);

  // The server will listen on port 44000.
  config.port = 44000;
  config.host = '*ANY';

  // Add the end point / route.
  il_addRoute(config : %paddr(sayHello) : IL_GET : '/hello');

  // Starts the server.
  il_listen(config);
end-proc;

Our end point will just return a nice “Hello!” to the requestor.

dcl-proc sayHello;
  dcl-pi *n;
      request  likeds(IL_REQUEST);
      response likeds(IL_RESPONSE);
  end-pi;

  il_responseWrite(response : 'Hello!');
end-proc;

Compile

This program can be compiled like any other FREE RPG program:

CRTBNDRPG SRCFILE(MIHAEL/ILEASTIC) SRCMBR(ILHELLO) PGM(MIHAEL/ILHELLO)

As our web service is just a normal ILE program we can start it by simply submitting it with the SBMJOB command.

Start

SBMJOB CMD(CALL PGM(ILHELLO)) JOB(ILEASTIC) JOBQ(QUSRNOMAX) CURLIB(MIHAEL) ALWMLTTHD(*YES)

Note: Make sure that the library list is set correctly so that the job has access to all necessary objects.

Now you can query the web service with the tool of your choice like Insomnia, Postman, cURL, … or even your web browser.

The NETSTAT command with the parameter *CNN is sometimes helpful to find the corresponding job because it allows us to select the job by the port it uses.

What’s next?

As ILEastic is now also available via iPKG I might get some time to update the ILEastic tutorial : Tour of Champions. We’ll see :) .

Also thanks and kudos to Niels Liisberg for creating these wonderful projects noxDB and ILEastic.

Happy installing!

Mihael