Release notes, known problems, limitations, and workarounds affecting single-service projects

Multi-segment message support in IMS SOAP Gateway single-service projects

The Enterprise Service Tools IMSTM SOAP Gateway Single-service projects include support for multi-segment message passing programs (MPPs). You will be able to deploy the artifacts generated in RationalR Developerfor System zTM 7.5 when allof the following prerequisites are generally available:
  • IMS SOAP Gateway V10.2
  • IMS V10R1 IMS Connect
  • PTF for IMS V10R1 IMS Connect APAR PK69366
  • PTFs for Enterprise COBOL for z/OSR APAR PK65058

IBM Rational Developer for System z's COBOL Compiled XML Conversion has enhanced error checking that may issue updated message numbers IGZ0280S through IGZ0298S and new message numbers IGZ0299S through IGZ0303S

Problem Description: IBMR Rational Developer for System z's Enterprise Service Tools Compiled XML Conversion for CICSR, IMS, and Batch runtimes in the bottom-up and meet-in-middle scenarios may terminate with a return code of 280 through 303. The Language EnvironmentR message returned by the converter is either out-of-date or the text "Failed To Get Exception Message" is displayed to the system log or console.

Solution: Rational Developer for System z 's COBOL Compiled XML Conversion has enhanced error checking that may issue updated message numbers IGZ0280S through IGZ0298S and new message numbers IGZ0299S through IGZ0303S. Apply the PTF for APAR PK65058.

Additional mapping support in Web services for CICS scenarios

Web services for CICS scenarios have support for an additional mapping level and runtime level (2.2). To use the artifacts generated at this level you need CICS TS 3.2 with APAR PK69738 applied.

Information on PL/I to XML Type Derivation

In the topic: XML types derived from PL/I - Table 6 - PL/I to XML type is in error and should be ignored.

Copy Book causes Enterprise Service Tools wizard to hang

Problem: The Enterprise Service Tools wizard hangs when the required copybooks are not resolved. This happens when the Error messages language in the COBOL importer preference page is set to anything other than en_US.

Solution: Change Error messages language by selecting:

Window -> Preferences -> Importer -> COBOL -> More COBOL options tab

Meet-In-Middle import source files

Problem: In the meet-in-middle development scenario, importing from a File System... in Import source files wizard is not supported.

Workaround: Copy all the required files into a general project and then import them by selecting Workspace... in Import source files wizard.

Bottom-Up conflict with old WSDL/XSD files and new WSDL/XSD files

Problem: In the bottom-up development scenario, using an older version of generated WSDL/XSDs with newly generated converters might cause errors at runtime. For example, the following runtime error message can occur: IGZ0282S XML to data structure conversion could not complete in program "PGMNAME" because no element names in the XML document were recognized by the converter.

Solution: WSDL/XSDs generated with a converter should always be coupled with the converters.

XML Schema data type mapping for COBOL COMP-3 (PACKED DECIMAL) type

Problem: In the online help topic "XML types derived from COBOL" the row for COMP-3 (PACKED DECIMAL) should read as follows:
Table 1. COBOL to XML type derivation
COBOL Type COBOLUsageValue+ COBOL ModelType properties Corresponding XSD Type
packed-decimal, comp-3 -> packedDecimal packedDecimal
If decimal point is specified:

<xsd:simpleType>
<xsd:restriction base="xsd:decimal">
   <xsd:minInclusive value="xx.x"/>
   <xsd:maxInclusive value="yy.y"/>
</xsd:restriction>
</xsd:simpleType>

or, if decimal point is not specified:

<xsd:simpleType>
   <xsd:restriction base="xsd:short">
     <xsd:minInclusive value="xxx"/>
     <xsd:maxInclusive value="yyy"/>
   </xsd:restriction>
</xsd:simpleType>

Top-down/Meet-in-middle scenario with importing remote (z/OS Unix) WSDL file which includes, imports, or redefines a schema is not supported

Problem: In an Enterprise Service Tools project, if you are running Create New Service Implementation (top-down) scenario or Map to an Existing Service Interface (meet-in-middle) scenario, with the WSDL file (that was originally imported from a remote location) that includes, imports, or redefines a schema, it would fail with an error.

Workaround: Copy all the required files to the workstation or to a general project in the workspace and import the local WSDL file into the "Web Services for CICS Project" using RMB -> Import -> Source files and try the top-down scenario.

COBOL conversion routines generated by single-service wizards run in z/OS only

Even though the workstation COBOL compiler supports XML PARSE statements at both compile time and runtime, the COBOL programs generated by the single-service wizards are designed to run in the z/OS environment only.

XML Element nesting depth

Problem: The XML to language structure converter returns the following exception message:

IGZ0291S XML to data structure conversion could not complete
in program program-name because the maximum XML element
nesting depth was exceeded. The error occurred at element
element-name with character content character-content.

Workaround: The XML to language structure converter could not handle the nesting depth of a particular XML element. Though there is an allowance for nesting levels beyond that of the original COBOL structure, it can be exceeded. If an element exists in the request XML document that is not in the schema, the element will cause this condition if its nesting level is too deep.

FILLER items in COBOL data structures

Problem: Unnamed groups and their elementary items are not available for selection on the data structure selection page or the mapping session editor because the parent item is filtered out along with its elementary items.

Workaround: Edit the COBOL data structure and give names to the groups and/or elementary data items that require conversion. Giving a name to the COBOL group makes its non-filler elementary items available for selection.

OPT compiler option conflict

Problem: The OPT compiler option in the generated PROCESS statement in driver and converter programs will conflict with the TEST option if you specify it as a compile option in your JCL.

Workaround: If you want to debug the generated XML converter programs, deselect the "Optimization" check box in the "Specify compiler-related preferences" group on the "Generation options" page in the Web service wizard.

Automatic Match Mapping of COBOL groups containing OCCURS DEPENDING ON items

Problem: If a COBOL data item is, or contains, an ODO item, you cannot perform a "Match mapping" action with a compatible XML structure unless you manually map the ODO object before attempting the Match mapping action.

Workaround: Prior to attempting the Match mapping action, manually map the ODO object according to the mapping rules. (In the XML document, the element mapped to the COBOL ODO object item must appear before the XML element that is mapped to the corresponding COBOL ODO subject.)

Case sensitivity of certain text entry fields in XML Enablement wizards

Problem: Folder and file name entries are case sensitive in Eclipse on WindowsR.

Workaround: Make sure that you enter folder and file names consistently. For example, if your folder name shows as MyFolder in the Workbench, you must type MyFolder in an entry field requesting a folder name. If you enter myfolder, for example, the tools may flag this as an invalid or non-existent folder name.

Invalid pointers cause infinite loop

Problem: Providing non-null invalid pointers to XML converters or drivers causes an infinite loop.

Workaround: The XML converters attempt to detect and report null pointers passed by the caller. For non-null invalid pointers, the XML Converters will likely encounter and return, a protection exception (SOC4).

Support for DBCS data members with SOAP for CICS and Web Services for CICS

Support for DBCS data items in Enterprise Service Tools single-service projects requires that the request and response XML documents are encoded in UTF-16 or UTF-8. If the target runtime of the Web service is SOAP for CICS, configure the feature to exchange XML in UTF-8 or UTF-16 with the XML Converter Driver. The Web Services for CICS runtime will exchange XML in UTF-8 with a client by default while the XML Converter Driver exchanges XML with CICS in UTF-16; when UNICODE is needed, UTF-16 is the most efficient choice currently for the XML Converters. For either runtime, it might be necessary to configure z/OS support for UNICODE with a conversion image that supports conversion between UNICODE and the DBCS host codepage.

Generate -> XML File... menu item does not honor XSD schema restrictions

Problem: The Generate -> XML File... menu item does not honor restrictions in an XSD schema. Using the Generate XML File action on an XSD created by Enterprise Service Tools could lead to the generation of invalid XML files.

Workaround: Edit the generated XML file so that the tag contents conform to the restrictions specified in the XSD schema.

XML and Web Services batch processor: Invalid entries in configuration XML may cause null pointer exceptions during the batch process

Problem: Invalid entries in the options XML files (Container.xml, PlatformProperties.xml, ServicesSpecification.xml) may cause null pointer exceptions during the execution of the batch processor.

Workaround: Follow the format for correctly specifying entries in the options XML files.

XML and Web Services batch processor: Specifying directory for input language file location

The location of the COBOL input files can be specified in the "importDirectory" attribute as an absolute path, starting with the drive specification (for example, C:\mypath\test).

If, instead, a relative path is desired (for example, so that the configuration files and Cobol source code can be relocated without changing any file locations in the xsebatch configuration files), try doing the following:
  1. Omit the importDirectory attribute in InputOutputMessage, InputMessage, or OutputMessage elements in the service specification file.
  2. Include the relative pathname in the value of the importFile attributes. (For example, importFile="cobol_src/DFH0ACDT.cbl" or importFile="../cobol_src/DFH0ACDT.cbl".) These paths will be relative to the location from which xsebatch was invoked.
  3. If you use ".." to descend into parent directories, make sure that you have no more than one ".." in the importFile attribute values.

For example, suppose you have a project with the following directories:

C:\workspace\account_details
-- main project
C:\workspace\account_details\cobol_src
-- subdirectory with COBOL source files to import
C:\workspace\account_details\xsebatch_config
-- subdirectory with XML configuration files for xsebatch

Then you could use the following InputOutputMessage element for a COBOL source file called DFH0ACTD.cbl in the cobol_src directory:

<InputOutputMessage importFile="../cobol_src/DFH0ACTD.cbl"></InputOutputMessage>

Alternatively, you may place the COBOL source files in the same directory from which xsebatch is invoked

XML and Web Services batch processor: Specifying data names in mixed case

Even though the COBOL data names are not case sensitive, you need to specify the exact case in the specification xml files. For example, if in the COBOL data source, the data name is called MY-Data, in the Service specification xml the nativeTypeName attribute must be set to nativeTypeid="MY-Data". If you don't specify the exact case, the data name will not be found and the first available level 01 data name will be used by default.

Restriction on figurative constants LOW-VALUES and HIGH-VALUES

Figurative constants LOW-VALUE(S) and HIGH-VALUE(S) can be present in COBOL data structures used in the single-service wizards, but their semantic meaning is ignored by the single-service wizards and is not carried into the artifacts generated by these Enterprise Service Tools single-service wizards

GB18030 characters in an Enterprise Service Tools single-service project name

Problem: Using characters from the GB18030 code page in an Enterprise Service Tools single-service project name causes errors to occur when you run an Enterprise Service Tools single-service wizard on files in the project.

Workaround: Do not use GB18030 characters when naming an Enterprise Service Tools single-service project.

Temporary files not always cleaned up

Problem: Afterrunning an Enterprise Service Tools single-service wizard, you maysometimes notice that temporary files (for example, ~DF45B.tmp) are left in the Enterprise Service Tools single-service project folder.

Workaround: If you see similarly named files in your Enterprise Service Tools single-service project after running an Enterprise Service Tools single-service wizard, you can safely delete such files.

Temporary project not always cleaned up

Problem: While an Enterprise Service Tools single-service wizard is running, you may sometimes notice that a temporary project (for example, ESTProject or ESTProjectN, where N=1,2,3....) appears momentarily in the EST Project Explorer view during WSDL generation. The appearance of this project may momentarily shift the folders of the other projects in the EST Project Explorer. Sometimes when there are errors, or when the workbench is closed during the WSDL generation, these temporary projects are left in the EST Project Explorer.

Workaround: If you see similarly named projects in your workspace after running an Enterprise Service Tools single-service wizard, you can safely delete those projects.

When migrating version 6.0 mapping files (.cmx files) source files referenced by the .cmx file must be in the same folder

Problem: The migration process for the old mappin files requires that the referenced mapped source files be in the same folder as the mapping file. If this requirement is not met, the Mapping migration tool will fail with the following error message: "Resource ......[filename].mapping is not local".

Workaround: Move the referenced source files into the same folder as the mapping file that is being migrated.

Browsing to remote location in Web Service wizard causes workbench to lock up

Problem: Browsing to a remote location for a target folder (Converter folder, WSDL or WSBIND folder) in the Web service wizard pages may take a long time or lock up the workbench when the connection name is long (like ctfmvs08.rtp.raleigh.ibm.com)

Workaround: Rename the connection name to something shorter, like ctfmvs08.

Global element names in generated XML schemas are not consistent between Interpretive and Compiled XML conversion types

Problem: The web service message root element names in the XML schemas generated by default generation of Interpretive and Compiled XML conversion do not match. You may need to change the generation default of the Compiled XML conversion to match the Interpretive conversion case as described below in the Workaround section. This will let you change the conversion type from interpretive to compiled if needed later without having to re-publish the WSDL file and without changing code in clients of the web service.

Workaround: When generating the artifacts for Compiled XML conversion you can use the wizard to change the root element name to match the Interpretive XML conversion. This new option called "Root element name" is located in:

GenerationOptions page -> WSDL and XSD options Tab -> Specify request and response XML Schema propterties groups.

For example, the COBOL groupnamed A-B-C will cause the Interpretive conversion artifacts to havethe message root element name "a_b_c". The default Compiled conversionartifacts will have the root element name "ABC". As described earlieryou can change "ABC" in the wizard to "a_b_c" to match with the WSDLgenerated for the interpretive conversion.

DBCS characters are not allowed in the name of thegenerated XML converter files

Problem: DBCS charactersare not allowed in the names of Partitioned Data Set members on z/OS.

Workaround: OmitDBCS characters when specifying the name of the XML converter files.Also, check that the default file names suggested by the Wizard donot contain DBCS characters.