Major Differences in RXS 3.x+
RPG-XML Suite 3.0 was a major refresh that contains many powerful new features, as well as including the functionality of previous releases. However, due to the scale of changes necessary to keep RPG-XML Suite modern and current with the latest features in the RPG language, the subprocedure APIs look very different from previous releases - they are not backwards compatible. There are a number of reasons for this.
16MB Field Support and RTNPARM
The first reason is that a major priority in RXS 3.0 was reducing the need for users to incorporate IFS file usage in their programs. In prior releases, working with XML data larger than 64K necessitated the usage of IFS files. Using IFS files is slower than keeping data in memory, causing this limitation to impact high-traffic web services. It also requires additional effort to ensure that unused IFS files are then deleted, a task that fell to the developer. For this reason, we implemented the ability to utilize 16MB fields in many areas where IFS files may have been required before. IFS files may still be used in these cases, but with the ceiling on the data limit raised, it becomes a design choice rather than forced on the developer.
However, IBM i OS 6.1 did not include the ability to effectively return more than 64K of character data from a subprocedure. Doing so would incur a significant performance penalty - the best balance in IBM i OS 6.1 is to pass fields larger than 16MB by reference, rather than return data.
In IBM i OS 7.1, IBM added the RTNPARM keyword. This keyword can be specified on the first parm of a subprocedure, and allows the subprocedure to return up to 16MB of data without the V6R1 penalty. This makes it the most ideal solution.
Not everyone is on IBM i OS 7.1, though, and we didn't want customers on IBM i OS 6.1 to be left out on the many significant features and changes. For this reason, we added prototypes for both versions - they function slightly differently, but ensure each OS release has the best possible scenario.
Prototypes will follow this general pattern:
IBM i OS 6.1
RXS_SubprocName( Output: Input: DataStructure );
IBM i OS 7.1+
Output = RXS_SubprocName( Input: DataStructure );
In most cases, this structure was not compatible with how subprocedures were designed in versions earlier than RXS 3.0 - this is why the API structure is completely revamped.
The RPG compiler will determine which method is required based upon the presence of a compiler-directive variable prior to including the RXSCB copybook:
IBM i OS 6.1
IBM i OS 7.1+
Configuration Data Structures
APIs now utilize qualified data structures very widely as a parameter to include details on how the subprocedure will operate.
A goal of RXS 3.0+ was to make code be more self-documenting. Some subprocedures in earlier releases had names that may not necessarily be clear unless you were already familiar with RPG-XML Suite - RXS_getUri, RXS_ignElemNamSpc, etc.