This article was originally posted on our RPG-XML Suite product website.
As part of the API design for the newest RPG-XML Suite version 3.x , a major goal was to take advantage of IBM’s support for 16MB RPG variables – introduced starting in V6R1. This was a great move by IBM, and provides some real advantages for developers working with XML web services that have a tendency to be rather variable in the number of characters contained in the XML that they process.
The Real World
A “real world” example of a web service that can vary greatly in XML character count is an order processing web service whose XML structure contains order header data as well as order detail data that repeats for each item on the order. Because the character count for the order detail portion of the data can vary a great deal depending on the number of items on the order, it’s entirely possible for the total XML character count to exceed the old limit of 64K. Exceeding the 64K limit would mean the XML is truncated within the variable and would result in a failed transaction, since the partial XML would not be valid. While most orders might have only a small number of items and the 64K limit would only be exceeded by a small percentage of orders, the reality is that the developer has to code for the maximum, since the requirement would always be to handle 100% of all orders. Since the XML character count would not always fit in a 64K variable, developers have been forced to code the application to use a STMF as a container to hold the XML — and since the XML character count is not always known in advance, the STMF container method had to be used even when the number of characters ends up being under the 64K size limit.
STMF = Extra Effort
When using a STMF as a container for the XML, the RPG program requires extra coding to specify the STMF name and path, performance is degraded slightly due to the extra disk I/O involved with STMF’s, and there’s often the need to write additional code for purging the unneeded STMF’s once the XML is processed.
16MB Variable = Easy Street (With one small curve)
By using 16MB variables, the need to use STMF’s as XML containers becomes a thing of the past. So while we knew the new RPG-XML Suite API’s needed to allow for the use of 16MB variables, one factor still complicating the design of the API’s was that returned parameters still had the 64K limit. This is because of performance and other considerations which prevented IBM from increasing the returned value length limit. Here’s some pseudo code that illustrates the 64K limit on a return variable:
Return64K = RXS_API( Parm16MB1 : Parm16MB2 );
So the returned value of Return64K was still restrained to a 64K limit, even after the normal parameters were expanded to allow up to 16MB lengths. If you need to return a value that exceeded 64K, you have to do it with a normal parameter and not a returned value. So for V6R1, the pseudo code for returning a 16MB value would be:
RXS_API( Return16MB : Parm16MB1 : Parm16MB2 );
Starting with V7R1, IBM introduced a workaround of sorts for the returned variable size limitation, with a new option called RTNPARM. (I’m not going to dive into all the aspects of using RTNPARM within an API/prototype, but you can refer to IBM’s RPG documentation for more information). This new option enables the prototype for the API to use the first parameter, Return16MB, and treat it as a “pseudo” returned value. I added the word “pseudo” because under the covers the V7R1 compiler does everything as it did in V6R1, but by placing the RTNPARM option on the first parameter and by not having a conventional return value in the prototype, the developer is then allowed to code the actual API call in the traditional style for a returned value:
Return16MB = RXS_API( Parm16MB1 : Parm16MB2 );
So V7R1 developers can use the more natural coding style for returning a value via an API call, while still being able to fully exploit the advantages of 16MB fields. The V6R1 version is slightly less intuitive, but gets you to the exact same result.
Prototypes on Autopilot
RPG-XML Suite version 3.x API’s that have 16MB return values are designed to support both the V6R1 API call style, as well as the V7R1 improvement that uses RTNPARM. This was accomplished by coding a V6R1 prototype as well as a V7R1 version of the prototype that contains RTNPARM for the first parameter. Regardless of whether you are running V6R1 or V7R1, you can just reference the RXSCB copybook which contains the RXS3 prototypes — and the proper version of the RXS3 prototypes will be automatically selected according to the OS version you have installed on your IBM i.
The only exception that will require manual intervention is when you have written and compiled code for V6R1 in the past, but have since upgraded to V7R1. In this case, when you recompile your V6R1 style RPG code under V7R1, you will either need to modify the API calls to account for the use of the traditional styled returned value API calls, or you can simply include these compiler directives to allow the code to continue to compile as though you were still running V6R1:
/DEFINE RXSV6R1
/COPY QRPGLECPY,RXSCB
Putting 16 MB variables to the test
Do you have existing XML web service communication needs that would benefit from using full 16MB variable support within RPG-XML Suite? Are you ready to declare STMF’s a thing of the past?
Contact us directly with any questions at sales@krengeltech.com.