Hidden Gems for IBM i – Remote Procedure Call (RPC)

Posted by Francisco Hoya on Oct 13, 2013 11:00:00 PM


RPC is definitely one of the hidden gems on IBM i.  

RPC can easily call IBM i commands, IBM i APIs and IBM i Program objects without any setup of the complexities such as driver installation, or the injection of code into IBM i programs. In order to use RPC you just need to start the RPC server on the IBM i (which is typically started by default) and then call it. It’s simple and powerful and brings IBM i applications to remote devices.

In the following examples I will show you how useful RPC can be with looksoftware products, and hopefully it will provide you with ideas to extend and modernize your own IBM i applications.


Calling stored procedures

I’ll start out with a simple example calling a Stored Procedure on the IBM i.  Figure 1 illustrates a simple SQL stored procedure that inserts a record into a log file of user sign-ons.

RPC Fig1 SQL stored procedure

Figure 1: SQL stored procedure that inserts one record – ADD_HST

We could call a stored procedure directly in theory however best practice is to create a RPG program that is a wrapper for the stored procedures. This approach provides the following benefits:

  • Easier to maintain
  • Provides more flexibility in managing the result sets
  • Better control over input and output parameters
  • Can allow for conversion of the outputs of the stored procedure e.g. to JSON, XML and CSV
  • Allows for better error handling

Figure 2
shows a RPG program, called “COLTSTLOG”, that wraps around the stored procedure.

RPC Fig2 SQL Embedded RPG program

Figure 2: SQL Embedded RPG program - COLTSTLOG

Section A shows two parameters p_user and p_device which will be passed through to the embedded SQL calling the stored procedure shown at section B. This code will insert a log entry related to the current user (p_user) and their display device (p_device) plus the current date and time. These four values correspond to the four values used in the stored procedure shown in Figure 1.  

The above example shows the simplicity of the wrapper and how values can be passed between the RPG program and the stored procedure. Let’s move on to calling the stored procedure via RPC.


RPC Fig3a IBMi SignOn iPhone

Figure 3a: IBM i Sign-On on an iPhone

Figure 3a
is a sign-on screen designed for the iPhone and it will pass the User ID and the Device ID to the RPG program after sign-on. A variable is used to capture the username from the sign-on screen which is defined within soarchitect’s design view as shown in Figure 3b.

RPC Fig3b variable soarchitect

Figure 3b: Assigning a variable to a field within soarchitect



RPC Fig4 RPC Call code snippet

Figure 4: RPC Call code snippet

Figure 4
is a code snippet of the RPC call using soarchitect. Section A shows connection to the RPC server on the IBM i.Section B shows the RPC Declare method that defines the program name (COLTSTLOG), its alias name (LogSignOnUser) and parameters. Parameter names don’t need to match the same names used within the called program. For the RPG programmers reading this you can think of them as RPG Prototype Parameters. In this example we don’t have any output parameters as the stored procedure is simply adding entries into a log file. The RPC Call method is calling the program using its alias name specified within the RPC declaration. The RPC Call then passes the username and device ID through as arguments. Section C then disconnects the RPC session.


The end result after calling the COLTSTLOG via RPC are entries in a log file as shown in Figure 5.


RPC Fig5 SignOn logfile newlook

Figure 5: Sign-On log file – NEWLOOK.TRANHIST

 RPC Fig6 1 Rewrite stored procedure RPG


 Fig6 RPG rewrite

Figure 6: Rewrite stored procedure using RPG


In this example we reused an existing stored procedure but in real modernization projects it’s more common to write new stored procedures using CL or RPG without SQL statements. Alternatively you could rewrite stored procedures by copying the stored procedure SQL statements into the SQL embedded within RPG programs (as shown in Figure 6 above) and call them by RPC.


Calling IBMi commands

Calling an IBM i command is really easy to do via RPC. The following example optimized for for smartphones demonstrates how to call IBM’s own Send Message Commands (SNDMSG, SNDBRKMSG). A new form for smartphones is shown in Figure 7. This is a new form created within soarchitect and is not based on any underlying host screen. It has a list of users that can be chosen to send messages to.

RPC Fig7 User list

Figure 7: User list


 RPC Fig8  Creating message

Figure 8: Creating the message


Figure 8 shows the optimized form used to input the message. If the SNDBRKMSG command is sent then the message will immediately appear to the intended user as shown in Figure 9. All of these screens have been optimized for the smartphone using soarchitect.


RPC Fig9 A break message

Figure 9: A break message


The code used to send the IBM i commands via RPC is shown below in Figure 10.

RPC Fig10 RPC Command code snippet

Figure 10: RPC Command code snippet


We could achieve the same result by calling an IBM API instead of calling IBM commands but in this example it was easier to use commands. We’d recommend looking for commands to call before looking for APIs as this will often be quicker and easier.



RPC provides a simple and direct way to work with IBM's or your own programs and APIs. Where programs and APIs don’t exist you can create your own by leveraging your existing RPG skills.

With RPC you don’t need to worry about separate connection drivers as RPC is built into looksoftware’s products.

Francisco Hoya

Blog Author
Francisco Hoya  
Software Consultant, looksoftware

To learn more about our products please visit our website.

Or request an assessment with our consultants today... 

looksoftware free assessment of your IBM i applications

Topics: IBM i, RPG Open Access, Application Modernization, RPC, SQL