Enterprise Service Tools - Release Notes

1.0 CICS Runtime environments
   1.1 PTF PK32131 for CICS Transaction Server for z/OS V3.1 required for the CICS Service Flow Runtime environment
   1.2 Service Flow Feature of CICS Transaction Server for z/OS V3.2

2.0 Additional functions
   2.1 Single service projects for IMS Info 2.0 runtime

3.0 Release notes, known problems, limitations, and workarounds
   3.1 Prerequisites required to use Enterprise Service Tools
   3.2 Selecting files to import from a z/OS host
   3.3 Automatically importing dependent COBOL files from a z/OS host
   3.4 Cannot import a COBOL copybook when the path contains characters other than ASCII 0x00-0x7f

4.0 Release notes, known problems, limitations, and workarounds affecting EST single-service projects
   4.1 Dynamic help button for "Conversion type" selection on the Enterprise Service Tools Wizard Launchpad.
   4.2 COBOL conversion routines generated by single-service EST wizards run in z/OS only
   4.3 XML Element nesting depth
   4.4 FILLER items in COBOL data structures
   4.5 OPT compiler option conflict
   4.6 Automatic Match Mapping of COBOL groups containing OCCURS DEPENDING ON items
   4.7 Case sensitivity of certain text entry fields in XML Enablement wizards
   4.9 Invalid pointers cause infinite loop
   4.10 Support for DBCS data members with SOAP for CICS and Web Services for CICS
   4.11 Generate -> XML File... menu item does not honor XSD schema restrictions
   4.12 XML and Web Services batch processor: Invalid entries in configuration XML may cause null pointer exceptions during the batch process
   4.13 XML types derived from PL/I: Correction to interpretation of decimal float PLI types
   4.14 XML and Web Services batch processor: Specifying directory for input language file location
   4.15 XML and Web Services batch processor: Specifying data names in mixed case
   4.16 Restriction on figurative constants LOW-VALUES and HIGH-VALUES
   4.17 Message name attribute in service specification has no effect on the message in WSDL
   4.18 Top-down scenario with importing remote (USS) WSDL file which includes, imports, or redefines a schema is not supported
   4.19 GB18030 characters in project name
   4.20 Temporary files not always cleaned up
   4.21 Temporary project not always cleaned up
   4.22 WAS 7.0 test environment must be installed as default
   4.23 When migrating version 6.0 mapping files (.cmx files) source files referenced by the .cmx file must be in the same folder
   4.24 Browsing to remote location in Web Service wizard causes workbench to lock up
   4.25 Global element names in generated XML schemas are not consistent between Interpretive and Compiled XML conversion types
   4.26 DBCS characters are not allowed in the name of the generated XML converter files.
   4.27 Multi-dimensional arrays not recognized in "Language structures" wizard page
   4.28 "Language structure" wizard page shows incorrect error for PL/I file
  
5.0 Release notes, known problems, limitations, and workarounds affecting service flow projects
   5.1 Keyword OF omitted in generated COBOL source code
   5.2 Limitations on PL/I importer
   5.3 Conflicting message and field names cause compile error
   5.4 Importing a COBOL copy book file fails when the path or file name contains non-English characters
   5.5 Importing a PL/I include file fails when the path or file name contains non-English characters
   5.6 Cannot import an included PL/I include file from a remote z/OS system

1.0 CICS Runtime environments

The CICS Service Flow Runtime environment (also known as the CICS Service Flow Feature) is the runtime environment for a Web service created from a service flow project in the Enterprise Service Tools.

1.1 PTF PK32131 for CICS Transaction Server for z/OS V3.1 required for the CICS Service Flow Runtime environment

For this release of the Enterprise Service Tools, if you are using CICS Transaction Server for z/OS V3.1 as the runtime environment, then you must be at a minimum PTF level of PK32131 for the CICS Service Flow Runtime for CICS Transaction Server for z/OS V3.1.

1.2 Service Flow Feature of CICS Transaction Server for z/OS V3.2

For this release of the Enterprise Service Tools, if you are using CICS Transaction Server for z/OS V3.2 as the runtime environment, then you must install the CICS Service Flow Feature of CICS Transaction Server for z/OS V3.2.

2.0 Additional functions

2.1 Single service projects for IMS Info 2.0 runtime

The Enterprise Service Tools Single service projects include capability that supports the upcoming IMS Info 2.0 runtime. You will be able to deploy the artifacts generated in Rational Developer for System z 7.1.1 when the IMS Info 2.0 runtime is generally available in a future release.

3.1 Prerequisites required to use Enterprise Service Tools

The following prerequisites are required to use Enterprise Service Tools:

3.2 Selecting files to import from a z/OS host

This note supplements the topics in the Enterprise Service Tools online documentation that describe how to import files into an Enterprise Service Tools project directly from a z/OS host.

Most of the wizards that allow you to import files into an Enterprise Service Tools project also allow you (assuming that you have previously done the correct configuration steps in the workbench) to import files directly from a z/OS host, by clicking the Remote button on the appropriate wizard page and then selecting the remote files to import from a directory tree that is generated via an active connection with the z/OS host. (Other options on the same wizard pages include the FileSystem button for selecting files to import from the workstation's file system and the Workspace button for selecting files to import from the current workspace that you are using in the workbench.)

Wizards that can import files directly from a z/OS host include:
  • The BMS Import wizard
  • The Import Web Services Definition wizard
  • The Import PL/I Files wizard
  • The New Flow wizard (on the Import COBOL Files page)
  • The New Service Flow Project wizard (on the Associate service interface page and on the Specify existing program definitions page)
  • The Import Source Files wizard
To import files from a z/OS host in one of these wizards, you must first configure and activate, in the workbench, one of the following types of connections to a z/OS host:
  • A z/OS connection in the Remote System Explorer (RSE) perspective.
  • A z/OS Project.

For information on creating and activating these connections, see the topics in the online documentation for the Rational Developer for System z that describe how to create a z/OS project and how to create a z/OS connection in the Remote System Explorer (RSE) perspective.

3.3 Automatically importing dependent COBOL files from a z/OS host

This note supplements the topics in the Enterprise Service Tools online documentation that describe how to import dependent COBOL files from a z/OS host.

The Enterprise Service Tools wizards that allow you to import COBOL files have an option to also automatically import any COBOL files upon which a COBOL file that you have selected to import has a dependency.

To perform this functionality of automatically importing dependency files, the Enterprise Service Tools wizard uses the View Dependency feature of the Rational Developer for System z. Before using this functionality, you must configure the View Dependency feature.

For more information, see the View Dependency topics in the online documentation for the Rational Developer for System z.

3.4 Cannot import a COBOL copybook when the path contains characters other than ASCII 0x00-0x7f

Problem: If you attempt to import a COBOL copybook from your workstation, and the path to the COBOL file contains a character (such as the German u-umlaut character) that is not in the ASCII character range 0x00-0x7f, then the import operation fails and an error message such as the following is displayed in the Remote Error List view:
The 'COPY' library was not found. Skipped to the period terminating the 'COPY' statement.

Workaround: Change the name of any subdirectory in the path that contains the problem characters so that the name contains only characters in the range ASCII 0x00-0x7f. Or, move the COBOL copybook to another subdirectory so that the path contains only characters in the range ASCII 0x00-0x7f.

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

4.1 Dynamic help button for "Conversion type" selection on the Enterprise Service Tools Wizard Launchpad.

Problem: When the "About" section in the dynamic help for the "Conversion type" selection is collapsed and expanded, the contents of the section change.

Workaround: To recover the dynamic help content for the "Conversion type" selection, close the dynamic help window and reopen it.

4.2 COBOL conversion routines generated by single-service EST 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 EST wizards are designed to run in the z/OS environment only.

4.3 XML Element nesting depth

Problem: The inbound 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 inbound 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 an inbound XML document that is not in the schema, the element will cause this condition if its nesting level is too deep.

4.4 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.

4.5 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.

4.6 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.)

4.7 Case sensitivity of certain text entry fields in XML Enablement wizards

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

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.

4.9 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).

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

Support for DBCS data items in EST single-service projects requires that the inbound and outbound 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.

4.11 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.

4.12 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.

4.13 XML types derived from PL/I: Correction to interpretation of decimal float PLI types

Problem: In the online help topic "XML types derived from PL/I", in the last two rows of Table 2, PL/I to XML type derivation, Binary Float and Decimal float, the values in the first column should be updated.

Workaround: The last two rows of Table 2, PL/I to XML type derivation, Binary Float and Decimal float, should read as follows:
PL/I Type Corresponding XSD Type
Decimal Float (n)
  • where n <= 6
<xsd:simpleType>
   <xsd:restriction base="xsd:float"/>
</xsd:simpleType>
Decimal Float (n)
  • where 7 <= n <= 16
<xsd:simpleType>
   <xsd:restriction base="xsd:double"/>
</xsd:simpleType>

4.14 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.

4.15 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.

4.16 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 EST single-service wizards, but their semantic meaning is ignored by the EST single-service wizards and is not carried into the artifacts generated by these EST single-service wizards.

4.17 Message name attribute in service specification has no effect on the message in WSDL

Problem: In batch mode, the "name" attribute of the message elements (InputMessage, OutputMessage, InputOutputMessage) in the Service specification file has no effect on the generated WSDL file. The default listed in the documentation ("esvc") is incorrect. The default is formed by concatenating the name of the Operation with the word "Request" (for InputMessage and InputOutputMessage) and with word "Response" (for the OutputMessage).

Workaround: You can rely on the default message name generated from the tools as described above or you can modify the generated WSDL after it is generated.

4.18 Top-down scenario with importing remote (USS) WSDL file which includes, imports, or redefines a schema is not supported

Problem: In the "Web Services for CICS Project", if you are running Create New Service Implementation (top-down) 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..

4.19 GB18030 characters in an EST single-service project name

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

Workaround: Do not use GB18030 characters when naming an EST single-service project.

4.20 Temporary files not always cleaned up

Problem: After running an EST single-service wizard, you may sometimes notice that temporary files (for example, ~DF45B.tmp) are left in the EST single-service project folder.

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

4.21 Temporary project not always cleaned up

Problem: While an EST 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 EST single-service wizard, you can safely delete those projects.

4.22 WAS 7.0 test environment must be installed as default

Problem: When WAS 7.0 test environment is not installed by default during the RAD 7.0 install process, you may encounter errors testing Java client proxies generated from WSDL. These errors will happen even if you do install WAS 7.0 test environment later.

Workaround: Take the default installation options for WAS 7.0 during RAD install process if you plan to generate and test Java client proxies for web services.

4.23 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.

4.24 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.

4.25 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 "Generation Options" page->"WSDL and XSD" options Tab->"Specify inbound and outbound XML Schema propterties" groups. For example, the COBOL group named A-B-C will cause the Interpretive conversion artifacts to have the message root element name "a_b_c". The default Compiled conversion artifacts will have the root element name "ABC". As described earlier you can change "ABC" in the wizard to "a_b_c" to match with the WSDL generated for the interpretive conversion.

4.26 DBCS characters are not allowed in the name of the generated XML converter files.

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

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

4.27 Multi-dimensional arrays not recognized in "Language structures" wizard page

In the "Language structures" page of the "Enterprise Service Tools Wizard", multi-dimensional arrays are considered unsupported types for PL/I source files

4.28 "Language structure" wizard page shows incorrect error for PL/I file

Problem: When running the "Enterprise Service Tools Wizard" on a PL/I file without any compile errors, the "Language structures" wizard page might display the following error:

Please select an inbound language structure.

Workaround: Cancel and restart the wizard.

5.0 Release notes, known problems, limitations, and workarounds affecting service flow projects

5.1 Keyword OF omitted in generated COBOL source code

Problem: When you generate runtime COBOL source code for the CICS Service Flow Runtime, on rare occasions the code-generating program does not include the OF keyword between the data names of an identifier. For example, the incorrect text MYFIELDMYSMESSAGE is generated instead of the correct text MYFIELD OF MYMESSAGE.

Workaround: In the workbench's main menu, select Project > Clean. Then generate the runtime COBOL source code again. The data names of identifiers should now be generated correctly.

5.2 Limitations on PL/I importer

Problem: When you import a PL/I program containing CICS commands that is compiled on the host using the CICS option of the host's PL/I compiler, the PL/I importer will fail with a message stating that any CICS command is an externally defined function. This is because the CICS option of the host's PL/I compiler automatically includes the CICS commands, but the PL/I importer cannot detect where these commands are included.

Workaround: Copy the program's data definitions into a separate include file (*.inc) and import the include file. This will avoid any problems with CICS commands or other perceived syntax errors in the full PL/I program.

5.3 Conflicting message and field names cause compile error

Problem: When you model a flow, and a field of one message has the same name as another message, the generated COBOL code may not compile, reporting a IGYPS0037 error, due to the naming conflict. For example, if the flow references (1) a message called 'X' with a field called 'Y' and (2) a message called 'Y', when the generated code refers to item 'Y' the COBOL compiler will not know whether the reference is to the message 'Y' or the field 'Y OF X'.

Workaround: Refactor either the message or the field to resolve the name conflict. In the EST Project Explorer, select one of the items with the duplicate names. Open the context menu and choose Rename.

5.4 Importing a COBOL copy book file fails when the path or file name contains non-English characters

Problem: If you attempt to import a COBOL copy book file, and the file path or the file name contains non-English characters, then the import fails.

Workaround: Rename the COBOL copy book file so that the name contains only English characters. Locate the file in a directory whose path contains only English characters.

5.5 Importing a PL/I include file fails when the path or file name contains non-English characters

Problem: If you attempt to import a PL/I include file, and the file path or the file name contains non-English characters, then the import fails.

Workaround: Rename the PL/I include file so that the name contains only English characters. Locate the file in a directory whose path contains only English characters.

5.6 Cannot import an included PL/I include file from a remote z/OS system

Problem: When you import a PL/I source file from a remote z/OS system, and the PL/I source file specifies PL/I include files that the source file wants to include, the Import PL/I Files wizard does not import the PL/I include files from the remote z/OS system.

Workaround: To import the PL/I include files:

  1. Download the PL/I source file and the PL/1 include files that the PL/I source file includes to a directory on your local file system or to a subfolder in your workspace.
  2. Import the PL/I source file from the local directory or workspace. The wizard imports not only the PL/I source file but also the PL/I include files that the PL/I source file includes.



Terms of use | Feedback

(C) Copyright IBM Corporation 2005, 2006, 2007. All Rights Reserved.