04
Mon, Nov
1 New Articles

Execute Remote Stored Procedures from the iSeries

General
Typography
  • Smaller Small Medium Big Bigger
  • Default Helvetica Segoe Georgia Times

In multi-application, mixed-platform environments, it's often necessary to have a job run on platform A to collect data for a job to be run on platform B. Since these diverse platforms often do not know how to "speak" to each other, one common solution has been to put the jobs on separate job schedulers, hope they run correctly, and merge the data later. However, for remote servers with SQL database engines, you can easily kick off a stored procedure (i.e., program) from the iSeries using Java.

As an example, we'll have the iSeries execute a simple stored procedure on an SQL Server machine and return the results to an RPG program. This method is so transparent that you won't be able to tell whether the stored procedures were executed on your local iSeries or on a database server on the other side of the world!

To use this technique, the iSeries requires a minimum of OS/400 V4R5, the Developer Kit for Java 5722-JV1, and Toolbox for Java 5722-JC1. To use the SQL Server demonstration, you'll need SQL Server 2000 (or the Microsoft Desktop Engine 2000) and the SQL Server 2000 JDBC driver (Service Pack 2). The sample RPG program uses embedded SQL and therefore requires the SQL Development Kit to be installed. Alternatively, if you're on at least a V5R2 system, the RPG program can be rewritten as a DB2 SQL stored procedure, thereby potentially eliminating the need for the SQL Development Kit.

The hypothetical example shown in Figure 1 consists of a financial app running on the iSeries that needs information from an SQL Server hosted order entry app before it can finish.

http://www.mcpressonline.com/articles/images/2002/RemoteStoredProcedureExecutionV401030500.png

Figure 1: JDBC can bridge the communication gap between database servers. In this example, the iSeries executes and retrieves the results from a stored procedure running on a remote database server. (Click image to enlarge.)

A Quick Review

In "Query Remote Database Tables from the iSeries Using SQL and Java," I demonstrated how a user-defined table function (requires V5R2) can be written to allow the iSeries to execute a query on SQL Server (or any database that has a JDBC driver) and treat the result set as though it were a local table.

You may need to review the following topics covered in that article:

  • How to install the SQL Server JDBC driver jar files so that DB2 SQL can use them
  • Where to place Java classes so that DB2 SQL can use them

 

The SQL Server Stored Procedure

Figure 2 shows the spDailySales T-SQL stored procedure that I created in the "pubs" sample database that comes with SQL Server. (T-SQL is the name of SQL Server's SQL dialect.) The pubs database tracks orders from a chain of bookstores. This stored procedure returns information via output parameters about a given day's sales, including the top-selling book. The procedure has one input parameter and seven output parameters.

Create Procedure spDailySales
(@SaleDate  DateTime,
 @Qty       Integer Output,
 @No_Orders Integer Output,
 @No_Books  Integer Output,
 @Sales     Money   Output,
 @TopID     VarChar(6)  Output,
 @TopTitle  VarChar(80) Output,
 @TopSales  Money   Output)

As 
--
-- For the sample data, 09/14/1994 is the
-- date with the most data.
--

-- Get daily sales info
Select @Qty=Sum(Qty), 
       @No_Orders=Count(Distinct Ord_Num),
       @No_Books=Count(Distinct title_id)
  From Sales
 Where Ord_Date=@SaleDate

-- Get daily sales amount
  Select @Sales=Sum(Sales.Qty * titles.price)
    From Sales
    Join titles On titles.title_id=sales.title_id
   Where Ord_Date=@SaleDate

-- Get top seller info
  Select @TopID=Title_ID,
         @TopTitle=Title,
         @TopSales=Sales
    From (
  Select Top 1 
         sales.title_id As Title_ID, 
         titles.title As Title,
         Sum(Sales.Qty * titles.price) As Sales
    From Sales
    Join titles On titles.title_id=sales.title_id
   Where Ord_Date=@SaleDate
Group By sales.title_id, titles.title
Order By Sales Desc) As Sales

Return

Figure 2: Stored procedure spDailySales summarizes order data for a given day.

The Java Link

To allow the iSeries to communicate with SQL Server, we'll use Java's database capabilities. DailySales.java is a standalone Java program that establishes a connection with SQL Server and executes the spDailySales stored procedure. The CallableStatement class from the java.sql package is used when running a stored procedure that returns parameters.

Once we have a Java program written, how will we run it? Options include using Qshell, the Java Native Interface (JNI), etc. But one of the easiest is to make the program executable as an external stored procedure. This method allows us to use SQL's CALL statement to run the Java code and allows non-Java programmers to easily call the remote procedure. We'll need to modify DailySales.java slightly to do this.

Creating an iSeries Stored Procedure Wrapper: Two Paths to Travel

There are two options for creating a stored procedure wrapper around a Java class. The first method is to extend a special IBM-supplied class called StoredProc. The second is to create a Java class according to the SQLJ standard specification. (SQLJ is a group of companies consisting of IBM, Oracle, and others that meet for the purpose of defining standards for how SQL interacts with Java.)

We'll create two stored procedures and two Java programs on the iSeries to demonstrate both options:

  1. Procedure spDailySalesDB2, which conforms to the DB2General parameter style and uses Java class DailySalesDB2.class to connect to SQL Server
  2. Procedure spDailySalesSQLJ, which conforms to the SQLJ standard and uses Java class DailySalesSQLJ.class to connect to SQL Server

Don't be intimidated by the two options; the external stored procedure definitions and Java programs are almost identical.

Option 1: DB2 Stored Procedure Wrapper

DailySalesDB2.java contains the revamped code designed to be called as a stored procedure from the iSeries.

Here is the statement required to register the class for use with SQL as an external stored procedure:

Create Procedure xxxxx/spDailySalesDB2
(SaleDate  IN  Date,
 Qty       OUT Integer,
 No_Orders OUT Integer,
 No_Books  OUT Integer,
 Sales     OUT Dec(19,4),
 TopID     OUT VarChar(6),
 TopTitle  OUT VarChar(80),
 TopSales  OUT Dec(19,4))
Language Java
Parameter Style DB2General
External Name 'DailySalesDB2.dailySales'
Returns Null on Null Input
Not Deterministic
No SQL

Language Java specifies that the stored procedure is written in Java. The Parameter Style of DB2General indicates that the Java class being invoked will extend IBM's StoredProc class. The External Name keyword identifies method dailySales of class DailySalesDB2 as the method to run when DB2 runs the stored procedure.

Notice that the DB2 procedure signature (parameter list) is virtually identical to the signature in the SQL Server stored procedure. Since method dailySales will be run when the iSeries stored procedure is called, it must have a parameter list that is compatible with the stored procedure's signature. If you need help mapping data types between SQL and Java, see the section entitled "Parameter passing conventions for Java stored procedures and UDFs" in the IBM Developer Kit for Java.

Returning output parameters to DB2 is more than just populating parameter variables with values. StoredProc provides method set(), which must be called if parameter data is to be returned.

Passing NULLs with Primitive Types

Since Java's primitive types such as int and double cannot contain NULL values, the set method can be used as a mechanism for controlling whether the output parameters passed back to DB2 are NULL (similar to how a NULL indicator variable works in embedded SQL). In DailySalesDB2.java, the set method is conditionally invoked for "primitive" columns if the SQL Server stored procedure did not return a NULL.

parmQty=stmtDailySales.getInt(3);
if (!stmtDailySales.wasNull()) {
set(2, parmQty);
}

Set() takes two arguments: parameter number and value. The parameter number refers to the position of the parameter in the parameter list and is only useful for returning output parameters. If you do not call set for a given output parameter, the parameter will contain a NULL. You do not need to condition set when using non-primitives such as String variables, because they can contain NULLs. (Though not demonstrated, the companion isNull method inherited from StoredProc can be used to query if an input parameter for a primitive type is NULL.)

Once the parameters are set and the dailySales method is ended, control is returned to the database manager.

A Slight Detour: Dealing with String Parameter Data

One thing should be mentioned about passing string data between SQL and Java. CHAR and VARCHAR parameters are tagged with a default coded character set ID (CCSID) of 65535. This simply means that the string data is not necessarily associated with any particular character set. However, since Java stores its string data in Unicode, it needs to know what specific CCSID SQL is using so that the data can be translated correctly between an iSeries character set and Unicode. When the JNI encounters a parameter that has a CCSID of 65535, it will look to the job's CCSID to find out how the data should be translated to or from Unicode. If the string parameter's CCSID is 65535 and the job's CCSID is 65535, then the stored procedure call will fail because the string data cannot be translated. The lesson here is that if your jobs have a default CCSID of 65535, you'll have to override this setting to get Java and SQL to work together. You can easily do this with the Change Job command's CCSID parameter: CHGJOB CCSID(37).

As an alternative to changing the job's CCSID, the CCSID keyword may be specified on string data as follows:

TopID     OUT VarChar(6)  CCSID 37,
TopTitle  OUT VarChar(80) CCSID 37,

Specifying a CHAR or VARCHAR parameter with the optional CCSID parameter allows the correct translation between the iSeries character set and Unicode. However, while this technique worked with simple examples I tested with character parameters, I was not able to get it to work with the spDailySales stored procedures, probably because these procedures use the date data type. (The SQL date data type is problematic because, in my mind, it is a specialized character variable, but the CREATE PROCEDURE statement doesn't allow a CCSID to be specified on a date parameter.) I'm guessing that the job's CCSID is used to learn how to translate date data between Java and SQL.

For your troubleshooting pleasure, on a V5R3 system, I received message SQL4304 with a reason code 4 when my job's CCSID was set to 65535. This useless error mentioned nothing of the CCSID issue, and I only bring it up in case you encounter it.

Option 2: SQLJ Stored Procedure Wrapper

DailySalesSQLJ.java shows an alternative way to create a stored procedure wrapper for a Java program. In this example, there is no special class to be extended. Under the SQLJ specification, the method to be called must be a non-instance method (i.e., public void static). Additionally, the specification states that output parameters are to be defined as single element arrays. Finally, there is no mechanism for passing NULLs to primitive types such as int. If you need to test or return a NULL primitive parameter, then you have to implement an alternative solution, such as using extra parameters to serve as "null indicators."

Here is the CREATE PROCEDURE statement required to register the SQLJ-compatible Java program.

Create Procedure xxxxx/spDailySalesSQLJ 
(SaleDate  IN  Date,
 Qty       OUT Integer, 
 No_Orders OUT Integer,
 No_Books  OUT Integer, 
 Sales     OUT Dec(19,4), 
 TopID     OUT VarChar(6), 
 TopTitle  OUT VarChar(80), 
 TopSales  OUT Dec(19,4))
Language Java 
Parameter Style Java 
External Name 'DailySalesSQLJ.dailySales'
Returns Null on Null Input 
Not Deterministic 
No SQL

The Parameter Style of Java is the only main difference from the prior CREATE PROCEDURE example. It indicates that the SQLJ standard was followed when writing the stored procedure code.

Note for V5R2 users: You may receive an SQL4304 error when running a Java stored procedure with the Java parameter style. This is apparently due to a setup bug in V5R2 and can be corrected with the following command:

ADDLNK OBJ('/qibm/ProdData/OS400/Java400/ext/runtime.zip') 
       NEWLNK('/qibm/userdata/Java400/ext/runtime.zip')

 

Which Option to Use When Creating a Java Stored Procedure?

Other than the NULL primitive issue and a few SQL-to-Java data mapping issues, there isn't much difference between the SQLJ and DB2 approaches to writing stored procedures using Java. The DB2 standard exists for things that are missing or inadequate in the SQLJ standard, such as allowing nullable parameters with primitive data types or user-defined table functions. However, for maximum portability to non-DB2 databases, the SQLJ standard should be used when writing SQL routines.

A Reminder on Creating Java Programs for Use with SQL

Don't forget to register the SQL Server JDBC driver's jar files (see "SQLJ procedures that manipulate JAR files" in the IBM Developer Kit for Java).

Don't forget that the .class files for all SQL routines (user-defined functions, user-defined table functions, and stored procedures) written in Java need to be placed in the special folder /qibm/userdata/os400/sqllib/function. See the program header for sample compilation instructions. During testing, once you re-compile the Java program, you may need to sign off and sign back on for the new program to take effect.

Once your code is working correctly, issue the CRTJVAPGM command to optimize the class file for running on the iSeries.

Running the SQL Server Stored Procedure from the iSeries

Now we have our Java program written to call the SQL Server stored procedure, and the iSeries stored procedure is defined to call the Java program, so the only step remaining is to call the stored procedure in a program. Because the stored procedure returns output parameters, we'll use embedded SQL to retrieve the results of the output parameters into host variables in an RPG program. (Of course, this can be done in any high-level language or even in SQL.)

Program DailySales.sqlrpgle.txt is used to execute the remote stored procedure. As shown here, a simple compiler directive allows you to choose which version of the stored procedure is called:

 /If Defined(#DB2)
C/Exec SQL
C+
C+ -- Call DB2General Stored Procedure (DB2 Specific extends
C+ -- StoredProc class)
C+
C+ Call spDailySalesDB2  (:SaleDate,
C+                        :Qty:NI,
C+                        :No_Orders:NI,
C+                        :No_Books:NI,
C+                        :Sales:NI,
C+                        :TopID:NI,
C+                        :TopTitle:NI,
C+                        :TopSales:NI)
C/End-Exec
 /Else
C/Exec SQL
C+
C+ -- Call SQLJ Stored Procedure (Generic class
C+ -- conforms to SQLJ standard)
C+
C+ Call spDailySalesSQLJ (:SaleDate,
C+                        :Qty:NI,
C+                        :No_Orders:NI,
C+                        :No_Books:NI,
C+                        :Sales:NI,
C+                        :TopID:NI,
C+                        :TopTitle:NI,
C+                        :TopSales:NI)
C/End-Exec
 /EndIf

Of course, in the real world, you probably wouldn't use the same null indicator variable for more than one host variable as I've done!

When the RPG program runs the stored procedure, the following occurs:

  1. DB2 calls the Java program.
  2. The Java program establishes a connection with SQL Server.
  3. The Java program calls the SQL Server stored procedure and retrieves the output variables.
  4. The Java program passes the output variables back to DB2.
  5. DB2 passes the host variables back to the RPG program.
  6. The RPG program displays the results from SQL Server.

In this example, the iSeries stored procedure call is used to retrieve data from SQL Server during a nightly iSeries batch run. With this technique, only one system is required to control a batch process that can run on multiple platforms. Further, the job can act upon any error handling and take appropriate action. This eliminates the uncertainty of working with two separate jobs on different systems that need to share data.

Food for Further Thought

This example only demonstrates retrieving output parameters from a stored procedure. If your stored procedure returns result sets, you have the option of writing the data to a temporary table or combining the technique described here with the technique described in the table function article ("Query Remote Database Tables from the iSeries Using SQL and Java"). With the table function, the result set of a remote stored procedure can become the output for a table function.

Remote stored procedure execution using Java allows the iSeries to perform real-time execution of stored procedures on other platforms. Wrapping the Java program with a stored procedure reduces complex Java integration to a simple CALL statement. Putting multiple database servers under the control of a single iSeries job can streamline and simplify multi-platform data integration issues.

Michael Sansoterra is a DBA for Broadway Systems in Grand Rapids, Michigan. He can be contacted at This email address is being protected from spambots. You need JavaScript enabled to view it..


BLOG COMMENTS POWERED BY DISQUS

LATEST COMMENTS

Support MC Press Online

$

Book Reviews

Resource Center

  • SB Profound WC 5536 Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application. You can find Part 1 here. In Part 2 of our free Node.js Webinar Series, Brian May teaches you the different tooling options available for writing code, debugging, and using Git for version control. Brian will briefly discuss the different tools available, and demonstrate his preferred setup for Node development on IBM i or any platform. Attend this webinar to learn:

  • SB Profound WP 5539More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.

  • SB HelpSystems ROBOT Generic IBM announced the E1080 servers using the latest Power10 processor in September 2021. The most powerful processor from IBM to date, Power10 is designed to handle the demands of doing business in today’s high-tech atmosphere, including running cloud applications, supporting big data, and managing AI workloads. But what does Power10 mean for your data center? In this recorded webinar, IBMers Dan Sundt and Dylan Boday join IBM Power Champion Tom Huntington for a discussion on why Power10 technology is the right strategic investment if you run IBM i, AIX, or Linux. In this action-packed hour, Tom will share trends from the IBM i and AIX user communities while Dan and Dylan dive into the tech specs for key hardware, including:

  • Magic MarkTRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now!  Request Now.

  • SB HelpSystems ROBOT GenericForms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.

  • SB HelpSystems ROBOT GenericIT security is a top priority for businesses around the world, but most IBM i pros don’t know where to begin—and most cybersecurity experts don’t know IBM i. In this session, Robin Tatam explores the business impact of lax IBM i security, the top vulnerabilities putting IBM i at risk, and the steps you can take to protect your organization. If you’re looking to avoid unexpected downtime or corrupted data, you don’t want to miss this session.

  • SB HelpSystems ROBOT GenericCan you trust all of your users all of the time? A typical end user receives 16 malicious emails each month, but only 17 percent of these phishing campaigns are reported to IT. Once an attack is underway, most organizations won’t discover the breach until six months later. A staggering amount of damage can occur in that time. Despite these risks, 93 percent of organizations are leaving their IBM i systems vulnerable to cybercrime. In this on-demand webinar, IBM i security experts Robin Tatam and Sandi Moore will reveal:

  • FORTRA Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:

  • FORTRAManaging messages on your IBM i can be more than a full-time job if you have to do it manually. Messages need a response and resources must be monitored—often over multiple systems and across platforms. How can you be sure you won’t miss important system events? Automate your message center with the Robot Message Management Solution. Key features include:

  • FORTRAThe thought of printing, distributing, and storing iSeries reports manually may reduce you to tears. Paper and labor costs associated with report generation can spiral out of control. Mountains of paper threaten to swamp your files. Robot automates report bursting, distribution, bundling, and archiving, and offers secure, selective online report viewing. Manage your reports with the Robot Report Management Solution. Key features include:

  • FORTRAFor over 30 years, Robot has been a leader in systems management for IBM i. With batch job creation and scheduling at its core, the Robot Job Scheduling Solution reduces the opportunity for human error and helps you maintain service levels, automating even the biggest, most complex runbooks. Manage your job schedule with the Robot Job Scheduling Solution. Key features include:

  • LANSA Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.

  • LANSAWhen it comes to creating your business applications, there are hundreds of coding platforms and programming languages to choose from. These options range from very complex traditional programming languages to Low-Code platforms where sometimes no traditional coding experience is needed. Download our whitepaper, The Power of Writing Code in a Low-Code Solution, and:

  • LANSASupply Chain is becoming increasingly complex and unpredictable. From raw materials for manufacturing to food supply chains, the journey from source to production to delivery to consumers is marred with inefficiencies, manual processes, shortages, recalls, counterfeits, and scandals. In this webinar, we discuss how:

  • The MC Resource Centers bring you the widest selection of white papers, trial software, and on-demand webcasts for you to choose from. >> Review the list of White Papers, Trial Software or On-Demand Webcast at the MC Press Resource Center. >> Add the items to yru Cart and complet he checkout process and submit

  • Profound Logic Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application.

  • SB Profound WC 5536Join us for this hour-long webcast that will explore:

  • Fortra IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn: