Converting XML to data structures using the CICS TRANSFORM command

This tip explains how to use the new CICS TRANSFORM command for converting XML to data structures and vice versa.

CICS continues to find new ways to skin cats. CICS/Transaction Server 4.1 introduced the TRANSFORM command, which a programmer can use to change XML into data structures and vice versa. While TRANSFORM may be used for Simple Object Access Protocol (SOAP) messages, it is more generalized and has wider application.

There are two pieces to this facility: the XML assistant and the TRANSFORM command itself.

XML assistant
It appears that IBM patterned the XML assistant after the Web services assistant released a few years ago. In fact, it does the same basic job of reading an XML schema or language structure to create metafiles that CICS uses to do conversions. But, being a more generalized processor, it doesn’t look for elements or structures specific to SOAP messages.

The assistant supports COBOL, PL/1, C and C++. DFHLS2SC converts language structures into XML schemas while DFHWS2LS creates language structures from XML schemas. Both utilities create bind files as well as resource-definition bundles and manifests. The assistants can create archives (.ZIP and .JAR) as well, but the contents must be decompressed before CICS uses them.

The bundle and manifest must be put in a directory pointed to by an RDO BUNDLE definition. Once the BUNDLE resource is in place, CICS will create an XMLTRANSFORM resource to which the TRANSFORM will refer.

Interestingly enough, the CICS manuals talk about compatibilities between the Web services and XML assistants. A language structure converted to XML via DFHLS2SC, then reconverted back with DFHWS2LS, will look different but be “logically equivalent,” although IBM warns that you might not be able to feed the massaged data structure back into DFHLS2SC (just in case you wanted to). The upshot is that you might be able to mix and match, but the best plan is to use the assistants consistent with their intended purpose.

Rational Developer for Z (RDz) can also produce the bind file and resource definitions in case you don’t want to use CICS’s free tool.

The TRANSFORM command
With the resource definitions in place, the next step is to actually utilize the bind file through the TRANSFORM command. There are two flavors for this. TRANSFORM DATATOXML takes an input data structure and transforms into XML. Conversely, TRANSFORM XMLTODATA converts XML into a language structure.

Both versions of the command must name the language structure and XML data containers as well as their channel. They must also specify the 16-byte XMLTRANSFORM resource name built from the bundle generated with the XML assistant or RDz.

The XMLTODATA command offers a few other operands that allow an application to get information about the XML before undergoing the transformation. For instance, a CICS program can get the name of the first element in the XML along with its namespace Uniform Resource Identifier (URI)

What does this mean for you?
The hard part is figuring out where the TRANSFORM command fits in with the myriad options for parsing XML.

There are several ways to convert XML programmatically. Writing your own transformation program might be fun but not generally recommended. RDz can generate a COBOL program using the PARSE verb. This eases the maintenance burden and creates a custom converter, which ought to perform better than a generic one. In addition, compiling the program with the XMLSS option makes the CPU spent doing the transformation work zAAP eligible.

CICS itself has an elaborate infrastructure for transforming XML SOAP messages into data structures, which has a couple of advantages. First, CICS performs the initial parse through z/OS XML Services, which is zAAP eligible. Second, if the infrastructure for bind and pipeline files is set up correctly, the application code need never touch XML. Instead, CICS hands a data area to the program as if nothing special happened.

On the other hand, the TRANSFORM command seems to be positioned as a general utility available whenever XML conversion is required.

It will work, for instance, if your application needs to handle raw XML from a SOAP request. Specifying XML-ONLY=TRUE when generating the bind file through the Web services assistant tells CICS to pass the SOAP message directly to the application. After accessing the message, the application may use the TRANSFORM command to get the information into a language structure. The TRANSFORM command may also enable installations to bypass CICS’s Web service interface altogether and allow applications to manipulate their own XML while communicating to other systems via HTTP protocol.

The TRANSFORM command could also be used outside the scope of any sort of Web communications, for instance, something as simple as converting an XML configuration file into a control block. It might also be used to extract or save documents (in the sense of real text) in XML format. In the future there may be XML saved in databases that CICS will need to unwind via TRANSFORM.

Ultimately, it comes down to knowing what you need and the most efficient way to get it. And, as always, your mileage may vary.

ABOUT THE AUTHOR: For 24 years, Robert Crawford has worked off and on as a CICS systems programmer. He is experienced in debugging and tuning applications and has written in COBOL, Assembler and C++ using VSAM, DLI and DB2.

What did you think of this feature? Write to SearchDataCenter.com's Matt Stansberry about your data center concerns at [email protected].

Dig Deeper on IBM system z and mainframe systems