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.
 

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.

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.

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.
 

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

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.

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

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.
 

Figure 7: User list

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.

Figure 9: A break message

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

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.

Summary

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.