Upgrading TransacXML to version 6.1.1

Introduction

The main aim with this service release has been to obtain significant performance improvements for the Java variant.

This release also enables support of the use of the 32 bit Java parser used but the iSeries.

Significant changes have been made to the basic functions used by the TransacXML patterns to make the performance improvement possible. Most of the changes should not have any effect on the existing applications - but a few does have implications that you must consider when upgrading to version 6.1.2.

The aim of this document is to describe the things you need to check before you upgrade - and describe some effects of the changes that you might see.

SERIOUS TransacXML issue when upgrading

SingleFetch - Retrieve next occurrence

In addition to retrieving the data for the scoping XMLElement entity, the standard SingleFetch function also retrieves a reference to the next occurrence of the XMLElement scoped by the parent element. This functionality can be used instead of using a ProcessGroup to process all instances of the XMLElement scoped by a parent element.

As part of the performance investigation that has been the source of most of the changes in this version, we found that this functionality does lead to a performance overhead - and that this in some cases can be quite significant.

To avoid this performance overhead, a new function option GetNextOccurrence has been introduced.

When the option is set to Yes, the SingleFetch function tries to retrieve the reference to the next occurrence.

When the option is set to No, the SingleFetch function does not retrieve the reference.

The default for this option has been set to No.

The reason for setting this option to No is that by far the most SingleFetch functions do not use this functionality (most XMLElements are not even repeating).

Task: Investigate use of NextOccurrence output from SingleFetch functions

To ensure that all of your functionality works as expected you must check whether you use the NextOccurrence output field from your SingleFetch functions.

In most cases, the use of the NextOccurrence output field will only be relevant for functions scoped by entities inheriting from the XmlRepeatingElement entity.

So to investigate this:

1. Find all entities inheriting from XMLRepeatingElement, find all calls of the SingleFetch function scoped by these entities.
2. For each call, check whether the Output.NextOccurrence is used in the calling program (this use will almost always be as a parameter to a later call to the same SingleFetch function).
3. If the NextOccurrence output is used, set the function option GetNextOccurrence to Yes for the SingleFetch function.

Another approach to this issue is to set the function option to Yes for all the SingleFetch functions - and then change it to No for the functions, where you know you do not use the Next Occurrence parameter (at least check the SingleFetch function used by performance critical applications).

This approach avoids the investigation described above.

If you do not already inherit through an abstract layer of you own, we recommend that you do the following:

And then change your inheritance from WSYXML/XmlElement to MyXmlElement.

If you already have an abstract layer, just change the option for the existing SingleFetch function.

Java Only - function option: OnlySequencedNextOccurrences

For the Java variant, we found that if the elements you want to retrieve using the next occurrence option are followed by a large number of other elements, the last call of the SingleFetch function will take a long time (as the function tries to find an element that is not there).

To avoid this overhead an additional function option OnlySequencedNextOccurrences has been introduced.

This option instructs the function to stop trying to find the next occurrence if the immediate sibling is not the correct element.

This means that if you have the document:

• If the OnlySequencedNextOccurrences option is set to Yes for B.SingleFetch, you will only read the three first occurrences of B when using the NextOccurrence functionality.
• If the OnlySequencedNextOccurrences option is set to No for B.SingleFetch, you will read all 4 occurrences of B.

Unless you have a structure like the one shown above, where the elements you want to traverse is interspersed with other elements we recommend that the option is always set to Yes.

Java Only - New file name allocation for WSYSOAP

For the Java variant, it was possible that if in cases of high load, the names of the temporary files used by the SoapGenerators and SoapProcessors was not unique. This meant that two processes could use the same filename, with unpredictable consequences.

The name allocation for the temporary files has been changed so instead of using an integer as the unique part of the file identification we now use a UUID.

No action is required. but you will notice that the names of the local files have changed.

Java Only - New parser used

To make it possible to use the 32 bit parser on the iSeries we have chosen to change from the SUN parser to the xalan/xerces parser.

This means that you have to deploy some additional jar files with your application.

This can also mean that the namespace declarations are inserted in new locations in the document. As the position (and number) of namespace declarations is quite loosely defined in the XML standards, this does not mean that the generated XML is invalid - or even has a different meaning.

No action is required, just be aware that the content of the generated files can change - and that this no necessarily is an error.