Batch processor and WSDL to PL/I mapping

The batch processor in Rational® Developer for System z® generates the data structure, XML converters, and PL/I application template file from the WSDL file that describes the web service.

The batch processor is a command-line utility and requires three generation properties files as the input:

Table 1. Generation properties files for the top-down PL/I application generation approach
File Description
Container.xml The top-level generation properties file is used by the batch processor to create web services implementation artifacts and message converters.
PlatformProperties.xml This file specifies the default options properties that reflect your target runtime environment. The options affect the processing of the language types that are used in producing XML schema descriptions of web service messages that are based on that language type.
ServiceSpecification.xml This file specifies the options required to generate new web service interfaces or web service implementations. You can also override certain options that you specify in the PlatformProperties.xml file.

WSDL to PL/I mapping

The WSDL2PLI component in Rational Developer for System z generates metadata to record the high-level relationships between the WSDL file that you supply and the WSDL2PLI-generated artifacts. 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.

In Rational Developer for System z V9.0, the WSDL2PLI component uses a set of segmentation APIs in the IRZPWSH include file that is required during compilation of the PL/I program. Starting Rational Developer for System z V9.0.1, the WSDL2PLI component uses the segmentation APIs in the DFSPWSH include file that is part of IMS V12 (APAR PM97469) and IMS V13 (APAR PI17898). These APIs define how to consume and produce IMS messages.

The IRZPWSH module (in the SFEKSAMP data set in Rational Developer for System z V9.0 or earlier version) or DFSPWSH module (in the SDFSSMPL data set in IMS), provides the PL/I binding and offers pointers to the data structures.

For each operation on the specified service and port, WSDL2PLI generates:
  • The PL/I structure(s) for operation input message
  • The XSD to PL/I mapping session for operation input message
  • The PL/I structure(s) for operation output message
  • The PL/I to XSD mapping session for operation output message
WSDL2PLI generates the following output:
  • The WSDL2ELS metadata that is used to generate the IMS application template, IMS correlator file, and the XML converters.
  • A log file
Finally, the batch processor generates the following files:
  • The XML converter driver for each operation in the WSDL2ELS metadata for the input and output messages.
  • A multi-operation IMS correlator file
  • An IMS service provider application template

Rational Developer for System z  offers flexibility in the converter file naming convention to avoid possible name collisions for multiple conversion source packages. A conversion source package is generated for each language data structure. By default, the WSDL name is used as the converter file name prefix. If the name of the input WSDL file is longer than 6 characters, the first 6 characters are used to form the default name of the converter, with an added letter D at the end. If the WSDL file name ends with a number, the number increments for each additional conversion source package and is encoded in hexadecimal values to maximize the number of unique file names that can be formed within the 8 character limit.

You can also specify SOAP faults messages for each operation. The operation-level fault messages can be used to report business logic related issues, such as invalid account number. If a custom SOAP fault message is specified in the WSDL file, a converter is generated for the fault message.

Rational Developer for System z  supports additional generic PL/I binding for SOAP header XML pass-through. A structure is created in the generated application template for the client application to access and parse the SOAP header content. The client application is responsible for parsing and processing the header information, if there is any.

The following compatibility table describes the version of Rational Developer for System z that you should use depending on the IMS version, and the differences between the WSDL-to-PL/I segmentation APIs in the two versions.
Table 2. WSDL-to-PL/I segmentation APIs location and compatibility
IMS version Rational Developer for System z version WSDL-to-PL/I segmentation API module name Data set that contains the module
IMS V12 and later Rational Developer for System z  V9.0.1 or later DFSPWSIO in IMS, with the DFSPWSH include file SDFSSMPL in IMS

For details about how XML schema data types are mapped to Enterprise PL/I data declarations, limitations and restrictions, the IRZPWSH segmentation APIs, and troubleshooting information, see the WSDL2PLI reference information in the Rational Developer for System z online help, or the Rational Developer for System z product information.