WSDL-to-PL/I segmentation APIs for adding business logic in generated PL/I templates

IBM® Developer for System z® generates metadata to record the high-level relationships between the WSDL file that you supply and the generated artifacts based on the PL/I segmentation APIs. Use this set of APIs to add your business logic before enabling it as a web service on IMS Enterprise Suite SOAP Gateway.

Important: The IRZPWSIO segmentation APIs in IBM Developer for System z V9.0.1 or older versions is renamed to DFSPWSIO in IMS. Starting with IMS Enterprise Suite V3.1 SOAP Gateway and IBM Developer for System z V9.0.1.1, you must use the DFSPWSIO segmentation APIs in IMS.

Language structures are written to a single include file that begins with an operation-to-language-structure dictionary comment. The metadata file is in XML format and is used by the batch processor to generate XML converters, deployment metadata, and template programs. Annotations are added to the generated source code to describe the relationships between the generated language structures and the XML schemas from which they are derived.

The annotations appear as language comments immediately preceding the definitions of the language structures or language structure members to which they apply. The WSDL2PLI component in IBM Developer for System z uses a set of segmentation APIs in the DFSPWSH include file that is required during compilation of the PL/I program. These APIs define how to consume and produce IMS messages. The DFSPWSH include file in the SDFSSMPL data set provides the PL/I binding and offers pointers to the data structures.

For each operation on the specified service and port, the following is generated:

The PL/I structure(s) for operation input message
The XSD to PL/I mapping session for operation input message
The PL/I to XSD mapping session for operation output message
The PL/I structure(s) for operation output message

For each operation in the WSDL, an operationNameHandler procedure and an operationNameImpl procedure are created in the generated template. The operationNameHandler procedure contains protocol logic while the operationNameImpl procedure is ready to be filled out and customized with your business logic.

A DFSPWSHK user exit is provided to demonstrate how you can inspect, modify, or replace the buffer which contains the current data structure that is being processed by the DFSPWSIO segmentation APIs. Customize the DFSPWSHK user exit if you need to inspect, modify, or replace data structures as they are processed by the DFSPWSIO APIs. The DFSPWSHK user exit allows you to keep track of whether or not a data structure has been modified or replaced via the dfs_in_struct_state and dfs_out_struct_state parameters. These and other parameters are documented in detail in the sample procedure and in IMS Version 14 Exit Routines.

The DFSPWSHK user exit is invoked by DFSPWSIO segmentation APIs when the APIs are called by XML converters in IMS Connect or by message processing programs. Therefore the DFSPWSHK exit must be compiled and linked into a data set such that IMS Connect and Message Processing Regions could find it by using the standard MVS™ search order (for example, STEPLIB and LINKLIST). The following diagram demonstrates how the DFSPWSHK exit is called by both the XML converters in IMS Connect and by message processing programs.

This diagram shows how the four APIs in DFSPWSIO that are used by the generated XML converter invoke the DFSPWSHK exit to inspect, modify or replace the input and output buffer before and after the message is processed by the message queue. The same set of APIs are also used by the message processing programs to invoke the DFSPWSHK exit before sending the response to the message queue.

DFSXSETS: This API is used by the PL/I XML converter in IMS Connect to set a language structure that contains either the SOAP header, SOAP body, or SOAP fault. This API does not copy language structures into the IMS Connect output buffer until it is instructed to do so through the parameter @dfs_commit_structs. It is an error to deallocate or otherwise invalidate structure pointers passed to the API via parameter @dfs_struct_ptr before instructing the API to commit (copy) all structures to the IMS Connect output buffer.
DFSQGETS: This API is used by the message processing PL/I program to get that language structure from the IMS Message Queue by using the CEETDLI in-terface. The language structure contains either a SOAP header, SOAP body, or SOAP fault. All language structures must retrieved from the IMS Message Queue prior to setting the language structures by using the DFSQSETS API.
DFSQSETS: This API sets a language structure that contains either the SOAP header, SOAP body, or SOAP fault. This API does not insert language structures into the IMS Message Queue until it is instructed to do so via parameter @dfs_commit_structs. Therefore it is an error to deallocate or otherwise invali-date structure pointers that are passed to the API through the @dfs_struct_ptr pa-rameter before instructing the API to commit (insert) all structures to the IMS Message Queue.
DFSXGETS: This API is used by the PL/I XML converter in IMS Connect to get a language structure that contains either the SOAP header, SOAP body, or SOAP fault. Since the IMS Message Queue is not available to XML Conversion in IMS Connect, language structures are retrieved from the IMS Connect input buffer. The expected format of the IMS Connect input buffer is an LLZZDATA byte stream.

For more information about the generated DFSPWSH include file, see IMS Version 14 Application Programming APIs.