Rational Developer for System z

Setting preferences for COBOL XML converters

To set preferences for COBOL XML converters, open the COBOL XML Converters page in the Enterprise Service Tools preferences.
These preferences affect single-service projects, including:

These preferences affect how runtime XML conversion programs generated by single-service wizards in the Enterprise Service Tools convert data between the XML format used in service requests and responses and the high-level language data structures used by COBOL:

To set generation preferences for runtime XML conversion programs:
  1. On the workbench menu bar, select Window > Preferences. The Preferences window opens.
  2. In the left pane of the Preferences window, select Enterprise Service Tools.
  3. Change the preferences:
    1. The preferences on the Basic tab are described in the following table:
      Preference: Effect of this preference:
      Converter program name prefix This input field specifies the stem of the program name that is included in the IDENTIFICATION DIVISION of each generated COBOL program. If you type ACCT, for example, the wizard identifies the input converter program as ACCTI, the output converter program as ACCTO, and the driver as ACCTD
      Author name This input field specifies the character string to be included in the AUTHOR paragraph of each generated COBOL program.
      Request code page This list box specifies the code page to be used for encoding the request XML message.
      Host code page This list box specifies the code page that is used by the z/OS host system.
      Response code page This list box specifies the code page to be used for encoding the response XML message.
      Decimal point is comma This check box controls how the comma and period characters are interpreted in numeric strings:
      • When you select this check box:
        • A comma is interpreted as a decimal point.
        • A period is interpreted as a thousands separator.
      • When you clear this checkbox (this is the default setting):
        • A comma is interpreted as a thousands separator.
        • A period is interpreted as a decimal point.
  4. The preferences on the Advanced tab are as follows:
    • In the Specify XML Schema generation options group:

      Generate minimum hierarchy in XML Schemas
      This check box controls the message format of the generated XML schema and consequently the parsing and generation of XML in the XML converters. XML converters based on XML schemas having minimized hierarchies tend to have better performance.
      • Select this check box if you want the XML converters to be generated so as to use a reduced XML structure hierarchy, when a more detailed structure hierarchy is not needed to uniquely identify each element in the structure.

        When there are elements with the same tag name, the name of the element that occurs later in the document is prefixed with as many of its parent tags as are required to produce a unique name. This method increases the efficiency of message processing clients and reduces the number and complexity of objects that need to be instantiated.

      • Clear this check box if you want the wizard to generate an XML schema that represents the full hierarchy of the language structure.
      Generate groups in XML Schemas
      This check box controls whether the XML converter includes groups in the generated XML schemas:
      • Select this check box if you want the XML converter to include groups in the generated XML schemas.
      • Clear this check box if you want the XML converter to include group "contents" inline instead of using group references. This option is useful for applications that do not support the use of groups and group references in XML schemas.
      Generate short complex type names
      The normal method for generating a complex type name is to concatenate the name of the group to the names of all the parents of the group, with an underscore character "_" after each name except the last.
      However, if this check box is selected, then a complex type name is generated by taking just the name of the group.
      For example, in this COBOL group:
      01 ServiceRequest.
        02 CommonHeader.
          05 HeaderType1.
            10 Element1     PIC X(10).
      the complex XML type name for the HeaderType1 element is:
      • servicerequest_commonheader_headertype1 if the check box is not selected.
      • HeaderType1 if the check box is selected.
      The shortening of complex type names allows for the generation of more compact client code (usually, Java™ class code) from the WSDL and XSD files containing the complex XML types.
      The setting of this check box has no effect on top-down or meet-in-middle scenarios.
      When shortening of a complex type name is attempted, a collision is possible if the short name of the type already exists as the result of a previously defined type for a group with an identical name but different parent group names. For example, in the following COBOL structure:
      01 ServiceRequest.
        02 CommonHeader.
          05 HeaderType.
            10 Element         PIC X(10).
        02 SpecificHeader.
          05 HeaderType.
            10 Element         PIC X(10).
      the type name of the HeaderType group under SpecificHeader collides with the type name of the HeaderType group under CommonHeader.
      In case of a collision all colliding names keep the original long type names. Thus, based on this example, the resulting type names are:
      • servicerequest_commonheader_headertype and
      • servicerequest_specificheader_headertype.
      The short name for a complex type is formed by taking the name of the XML element that has that type, plus some possible modifications. The rules for forming short names are:
      1. Take the name of the XML element that has the type (such as HeaderType1).
      2. If the name starts with a character that is an invalid character for Java names (for example, a digit), it is prefixed with a double underscore "__".
      3. If a hyphen "-" is present in the original COBOL group name it is replaced with a single underscore "_".
      4. The case of the group name is preserved.
      For example, the following group:
      03 2-In--B.
         04 var2 blank zero pic 999.99.
      results in the shortened complex type name __2_In__B.
      Generate comments in XSD
      Select this checkbox to cause the comments from the COBOL source code file to be generated as annotation documentation in the generated XSD and WSDL files (see Including COBOL source code comments in generated XSD and WSDL files)
      This option applies only to the bottom-up development scenario for generating a Web service, and applies only if you specify Compiled XML Conversion.
      Generate qualified XML elements in XML schemas
      This check box allows for generation of qualified XML elements in the XML schemas.

      This allows for the option to require all XML elements be qualified with a namespace and support generation of XML schemas that can be included in other schemas with lesser chance of namespace collision.

    • In the Specify Request XML converter behavior group:

      Validate root element namespace name
      Select this checkbox to enable validation of the target namespace of the root element in XML documents. The target namespace of the root element can be found in the XML schema which defines it.
      Use VALUE literals to initialize omitted data items
      Select this checkbox to enable initialization for data items in the request language structure that you have excluded from the Web service input data structure (see Initializing data items in the COBOL application's input data structure ).
      This option applies only to the bottom-up development scenario for generating a Web service, and applies only if you specify Compiled XML Conversion.
      Use VALUE literals to initialize empty data items
      Select this checkbox to enable initialization for data items in the request language structure that you have included in the Web service input data structure (see Initializing data items in the COBOL application's input data structure ).
      This option applies only to the bottom-up scenario for generating a Web service, and applies only if you specify Compiled XML Conversion.
    • In the Specify response XML converter behavior group:

      Language data
      This option controls how the response runtime XML conversion program handles characters in the response COBOL data that are illegal in the XML 1.0 specification:
      • Select Filter characters illegal in XML 1.0 if you want the conversion program to scan both non-numeric and numeric data in the language structure and convert any character that is illegal in the XML 1.0 specification to an EBCDIC, ASCII, or UNICODE space (depending on the response code page).
      • Select Halt on characters illegal in XML 1.0 if you want the conversion program to scan both non-numeric and numeric data in the language structure and cause an exception if characters illegal in XML 1.0 are found.
      • Select Do not check for illegal characters if you want the conversion program not to check for characters that are illegal in the XML 1.0 specification.

      For more information see Options for handling illegal XML characters.

    • In the Specify compiler-related preferences group::
      Optimization
      Select whether the optimization option is enabled for the COBOL compiler. When the check box is selected, the COBOL compiler will use optimization in generating runtime code from COBOL source code.

      If you are trying to debug a compile error in your COBOL source code, it is a good idea to clear this check box and recompile. Without optimization turned on, it is easier to determine which part of the COBOL source code is causing the error.

      Specify Enterprise COBOL compiler version
      Select the version of the COBOL compiler that you want to use.
  5. Click OK when done.

Feedback