Rational Developer for System z, Version 7.6

XSDBindSpec

Use this element of the ServiceSpecification.xml document to specify the generation options for the Native or Vendor XML binding file (XSDBind file).

The XSDBind file is used to install an XML transformation resource (XMLTRANSFORM) under CICS® Transaction Server version 4.1 and later. The XMLTRANSFORM resource is used by the CICS EXEC APIs, TRANSFORM XMLTODATA and TRANSFORM DATATOXML.

The XMLTRANSFORM resource can be used to perform the XML transformation in both directions (DATATOXML and XMLTODATA), for one XML document and for one data structure. This is in contrast to the WEBSERVICE resource in which transformation to an XML document can be different from the transformation to a data structure.

There are two kinds of XSDBind files that may be generated: Native XSDBind and Vendor XSDBind.

The following shows which generation properties are associated with each XSDBind file type and examples of how to specify them.

Native XSDBind (Interpretive XML Conversion):
  • Characteristics:
    • CICS performs XML conversion using an internal mechanism
    • Specify @type="interpretive" on the element PlatformProperties.xml/CodegenPropertyArray/CodegenProperty/@name="com.ibm.etools.xmlent.ui.GEN_CONVERSION_TYPE"
    • Include "MessageSpec" inside the element ServiceSpecification.xml/EISProject/EISService/Operation.

  • PlatformProperties.xml:
    <PlatformArray>
       <Platform>
          <CodegenPropertyArray>
             <CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_CONVERSION_TYPE" 
                      value="interpretive"/>
           </CodegenPropertyArray>
       </Platform>
    </PlatformArray>
  • ServiceSpecification.xml (bottom-up):
    <EISProject 
             xmlns="http:///com/ibm/etools/xmlent/batch/emf/BatchProcessModel.ecore" 
             name="CICSPROGProject">
       <EISService name="CICSPROG">
          <Operation>
             <MessageSpec  importFile="CICSPRG.cbl" importDirectory="."
                nativeTypeName="DFHCOMMAREA"/>
             <XseSpec>
                <XSDBindSpec fileName="CICSPROG.xsdbind" logFileName="CICSPRG.log"/>
             </XseSpec>
          </Operation>
       </EISService>
    </EISProject>
Vendor XSDBind (Compiled XML Conversion):
  • Characteristics:
    • CICS performs XML conversion using IBM® Rational® Developer for System z® generated XML conversion programs
    • Specify @type="compiled" on the element PlatformProperties.xml/CodegenPropertyArray/CodegenProperty/@name="com.ibm.etools.xmlent.ui.GEN_CONVERSION_TYPE"
    • Include "MessageSpec" inside the element ServiceSpecification.xml/EISProject/EISService/Operation.
  • PlatformProperties.xml:
    <PlatformArray>
       <Platform>
          <CodegenPropertyArray>
             <CodegenProperty name="com.ibm.etools.xmlent.ui.GEN_CONVERSION_TYPE" 
                      value="compiled"/>
          </CodegenPropertyArray>
       </Platform>
    </PlatformArray>
  • ServiceSpecification.xml (bottom-up):
    <EISProject 
          xmlns="http:///com/ibm/etools/xmlent/batch/emf/BatchProcessModel.ecore" 
          name="CICSPROGProject">
       <EISService name="CICSPROG">
          <Operation>
             <MessageSpec  importFile="CICSPRG.cbl" importDirectory="." 
                   nativeTypeName="FHCOMMAREA"/>
             <XseSpec>
                <DriverSpec fileName="CICSPRGD.cbl" driverType="XML_TRANSFORM_CICS"
                      programName="CICSPRG"/>
                <ConverterSpecIn  fileName="CICSPRGD.cbl" programName="BUP001"/>
                <ConverterSpecOut fileName="CICSPRGD.cbl" programName="BUP001"/>
                <XSDBindSpec fileName="CICSPROG.xsdbind"  logFileName="CICSPROG.log"
                      mappingLevel="VENDOR" minimumRuntimeLevel="VENDOR"/>
             </XseSpec>
          </Operation>
       </EISService>
    </EISProject>

Contained by

Contains

None

Attributes

Table 1 shows the attributes for XSDBindSpec.

Table 1. Attribute Specifications for XSDBindSpec
Fields Description

Attribute: bundle
Valid values: See Description
Required?: No
Default value: None

Specifies the path and name of the bundle directory. If you specify this value, the XML schema (which you must specify in the XSDSpec element) and the XML binding file is generated in the bundle directory and a bundle manifest is also created. The path information on this parameter overrides any path information on the XSDSpec fileName attribute and XSDBindSpec fileName attribute.

Attribute: ccsid
Valid values: See Description
Required?: No
Default value: See Description

Specifies the CCSID that is used at run time to encode data between the application program and the XML binding file. The value of this parameter overrides the value of the LOCALCCSID system initialization parameter. The value must be an EBCDIC CCSID that is supported by Java™ and z/OS® conversion services. If you do not specify this parameter, the application program uses the CCSID specified in the system initialization parameter, and the XML binding file is encoded in US EBCDIC (Cp037).

Attribute: charVarying (EISService)
Valid values: NO | NULL |
COLLAPSE | BINARY
Required?: No
Default value: NULL or COLLAPSE  
(See Description)

Specifies how character arrays in the language structure should be mapped when the mapping level is 1.2 and higher.
Note: This parameter does not apply to Enterprise and Other PL/I language structures.
The options you can select are:
  • NO - Character arrays are mapped to an xsd:string and are processed as fixed length fields. The maximum length of the data is equal to the length of the array.
  • NULL - Character arrays are mapped to an xsd:string and are processed as null terminated arrays. CICS adds a terminating null character when transforming from a XML document. The maximum length of the character string is calculated as one character less than the length indicated in the language structure. This value is the default for mapping levels 1.2 and 2.0.
  • COLLAPSE - Generate XML character data description with the whitespace attribute set to "collapse". This value is only available at mapping levels of 1.2 and higher. This value is the default for mapping levels 2.1 and higher.
  • BINARY- Any character arrays defined in the language structure are mapped to fixed length xsd:base64Binary fields in the WSDL rather than to xsd:string fields.
Required elements:
  • PlatformProperties.xml/CodegenPropertyArray/CodegenProperty
    • @name="CONVERSION_TYPE"
    • @value="interpretive"
  • ServiceSpecification.xml/EISService

Attribute: charVarying
(EISServiceImplementation)
Valid values: NO | NULL | YES
Required?: No
Default value: NO  

Specifies how variable length character data is mapped when the mapping level is 1.2. Variable length binary data types are always mapped to either a container or a varying structure. If you do not specify this parameter, the default mapping depends on the language specified. The options that you can select are:
  • NO - Variable length character data is mapped as fixed length strings.
  • NULL - Variable length character data is mapped to null terminated strings.
  • YES - Variable length character data is mapped to a CHAR VARYING data type in PL/I. In the COBOL, C and C++ languages, variable length character data is mapped to an equivalent representation that comprises of two related elements - data length and the data.
Required Batch Options:
  • PlatformProperties.xml/CodegenPropertyArray/CodegenProperty

    @name="CONVERSION_TYPE" @value="interpretive"

  • ServiceSpecification.xml/EISService

Attribute: charVaryingLimit
Valid values: See Description
Required?: No
Default value: 32767

Specifies the maximum size of binary data and variable length character data that is mapped to the language structure when the mapping level is 1.2. If the character or binary data is larger than the value specified in this parameter, it is mapped to a container and the container name is used in the generated language structure. The value can range from 0 to the default 32767 bytes.
Required Batch Options:
  • PlatformProperties.xml/CodegenPropertyArray/CodegenProperty

    @name="CONVERSION_TYPE" @value="interpretive"

  • ServiceSpecification.xml/EISService

Attribute: defaultCharMaxLength
Valid values: See Description
Required?: No
Default value: 255  

Specifies the default array length of character data in characters for mappings where no length is implied in the Web service description document, when the mapping level is 1.2. The value of this parameter can be a positive integer in the range of 1 to 2147483647.
Required Batch Options:
  • PlatformProperties.xml/CodegenPropertyArray/CodegenProperty

    @name="CONVERSION_TYPE" @value="interpretive"

  • ServiceSpecification.xml/EISService

Attribute: fileName
Valid values: See Description
Required?: No
Default value: See Description

Specifies the name of the output file

The default value is: Data source file name concatenated with ".xsdbind"

Attribute: inlineMaxOccursLimit
Valid values: 0 through 32767
Required?: No
Default value: 1

This attribute is equivalent to the INLINE-MAXOCCURS-LIMIT parameter of the CICS XML Assistant DFHLS2SC. The value is used to decide whether or not to in-line variable repeating content based on the value of the maxOccurs attribute from the source WSDL. The full description can be found in the CICS Transaction Server V 4.1 InfoCenter, see:

Attribute: logFileName
Valid values: See Description
Required?: No
Default value: See Description

Specifies the name of the log file generated by the XML Assistant. This attribute value is used only when the following is specified in the PlatformProperties.xml file: <CodegenPropertyname="com.ibm.etools.xmlent.ui. GEN_CONVERSION_TYPE "value="interpretive"/>

The default value is: fileName concatenated with ".log"

Attribute: mappingLevel
Valid values: 1.0 | 1.1 | 1.2 |
2.0 | 2.1 |2.2 | 3.0
Required?: No
Default value: 2.1

Specifies the version of the programmatic interface shared between CICS and the application. Generally, it is best to specify the highest mapping level that is available:
  • Mapping levels 1.0 to 1.2 are supported in CICS TS 3.1 with APAR PK23547 applied.
  • Mapping levels 1.0 to 2.1 are supported in CICS TS 3.2 with APAR PK59794 applied.
  • Mapping levels 1.0 to 2.2 are supported in CICS TS 3.2 with APAR PK69738 applied.
  • Mapping levels 1.0 to 3.0 are supported in CICS TS 4.1
The use of old mapping levels is only recommended when regenerating the XML binding files for XML transformation resources that were previously deployed with an old mapping level. The details on the mapping levels can be found in the online CICS Transaction Server Infocenter, see:
1.0
This is the CICS runtime default mapping level. For more information on mapping levels refer to CICS TS 4.1 documentation at: http://publib.boulder.ibm.com/infocenter/cicsts/v4r1/topic/com.ibm.cics.ts.webservices.doc/reference/dfhws_mappinglevels.html
1.1
Use this mapping level if you need to regenerate a binding file at this specific level.
1.2
This mapping level provides the following features:
  • It enables the CHAR-VARYING parameter on the DFHLS2SC tab and the DFHSC2LS tab of the preferences.
  • It supports VARYING and VARYINGZ arrays,
Note: Mapping level 1.2 requires APAR PK23547.

Attribute: mappingLevel (continued)
Valid values: 1.0 | 1.1 | 1.2 |
2.0 | 2.1 |2.2 | 3.0
Required?: No
Default value: 2.1

2.0
Use this mapping level for CICS TS 3.2.

For more information on mapping levels refer toCICS TS 4.1 documentation at: https://publib.boulder.ibm.com/infocenter/cicsts/v4r1/topic/com.ibm.cics.ts.applicationprogramming.doc/datamapping/dfhws_mappinglevels.html

2.1
Use this mapping level for CICS TS 3.2 with APAR PK59794 and later. At this level you can use the following features:
  • INLINE-MAXOCCURS-LIMIT (available on wizard page DFHSC2LS)

    This allows you to decide whether to map variably repeating content inline or to use the existing container based mapping. For additional details, refer to: Varying number of elements at mapping level 2.1 and above

  • XML-ONLY (available on wizard page DFHSC2LS)
  • WSDL-NAMESPACE (available on wizard page DFHLS2SC)

Support has been added for xsd:any and xsd:anyType (for DFHSC2LS), see:https://publib.boulder.ibm.com/infocenter/cicsts/v4r1/topic/com.ibm.cics.ts.applicationprogramming.doc/datamapping/dfhws_anytypesupport.html

2.2
Use this mapping level with a CICSS TS 3.2 region that has APAR PK69738 applied. Mapping level 2.2 provides the following support:
  • Elements with fixed values
  • Enhanced support for <xsd:choice> elements
  • Abstract data types
  • Abstract elements
  • Substitution groups.
3.0
Use this mapping level for CICS TS 4.1.

Attribute: minimumRuntimeLevel
Valid values: MINIMUM |
3.0 | CURRENT
Required?: No
Default value: MINIMUM

Specifies the minimum CICS runtime environment that the XML binding file can be deployed into. An error message is displayed if a level is selected that does not match the other parameters specified.
MINIMUM
The lowest possible runtime level of CICS is allocated automatically given the parameters that are specified.
3.0
The generated XML binding file deploys successfully into CICS TS 4.1
CURRENT
The generated XML binding file deploys successfully into a CICS region at the highest available runtime level as the one you are using to generate the XML binding file

Attribute: vendorConverterName
Valid values: See Description
Required?: No
Default value: See Description

Specifies the program name of the main program entry.

The default value is: DriverSpec/@fileName

Attribute: dateTime
Valid values: See Description
Required?: No
Default value: See Description

Specifies how the XML elements of xsd:dateTime type are mapped into CICS ASKTIME format. This attribute is only valid for the CICS interpretive conversion type. If it is specified for the Vendor (Compiled) conversion type, it is ignored.

This attribute is only valid at Mapping level 3.0 and higher.

If this attribute is specified in a top-down scenario (that is the XSDBindSpec is specified inside the EISServiceImplementation) then the valid values are:
  • PACKED15 (default)

    or

  • STRING
If this attribute is specified in a bottom-up (that is, the XSDBindSpec is specified inside the EISService) then the valid values are:
  • UNUSED (default)

    or

  • PACKED15

Attribute: dataTruncation
Valid values: DISABLED | ENABLED
Required?: No
Default value: DISABLED

Specifies how truncated data is treated by the CICS native conversion mechanism:
  • If set to ENABLED, CICS tolerates truncated application data and assumes that the missing data is set to nulls.
  • If set to DISABLED, CICS rejects the truncated data and issues an error message.
Note: The ENABLED setting is only supported at mapping levels 3.0 and higher.

Example

<XSDBindSpec fileName="CICSPROG.xsdbind"
         mappingLevel="VENDOR" logFileName="CICSPROG.log" ccsid="37" 
         minimumRuntimeLevel="VENDOR">
</XSDBindSpec>

Terms of use | Feedback

This information center is powered by Eclipse technology. (http://www.eclipse.org)