WSBindSpec

Edit online

Use this element of the ServiceSpecification.xml document to specify the generation properties for the Native or Vendor WSBind file.

The WSBind file is used to install a new Web service under CICS® Transaction Server version 3.1 and later.

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

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

Native WSBind (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"
    • Specify ServiceSpecification.xml/../WSBindSpec/@businessPgmName="name of CICS program"

  • 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>
         <OutputMessage importFile="CICSPROG.cbl" importDirectory="."
            nativeTypeName="DFHCOMMAREA"/>
         <InputMessage  importFile="CICSPROG.cbl" importDirectory="." 
            nativeTypeName="DFHCOMMAREA"/>
         <XseSpec>
            <WSBindSpec fileName="CICSPROG.wsbind" 
            uri="/cics/services/CICSPROG" logFileName="CICSPROG.log"
                  businessPgmName="CICSPROG"/>
         </XseSpec>
      </Operation>
   </EISService>
</EISProject>
Vendor WSBind (Compiled XML Conversion):
  • Characteristics:
    • CICS performs XML conversion using Developer for z/OS® generated XML conversion programs
    • Specify @type="compiled" on the element PlatformProperties.xml/CodegenPropertyArray/CodegenProperty/@name="com.ibm.etools.xmlent.ui.GEN_CONVERSION_TYPE"
    • Specify ServiceSpecification.xml/../DriverSpec/@driverType="WEB_SERVICES_CICS"
    • Specify ServiceSpecification.xml/../DriverSpec/@businessPgmName="name of CICS program".
  • 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>
         <OutputMessage importFile="CICSPRG.cbl" importDirectory="." 
               nativeTypeName="DFHCOMMAREA"/>
         <InputMessage  importFile="CICSPRG.cbl" importDirectory="." 
               nativeTypeName="DFHCOMMAREA"/>
         <XseSpec>
            <DriverSpec fileName="CICSPRGD.cbl" driverType="WEB_SERVICES_CICS"
               programName="CICSPRG"  businessPgmName="CICSPROG"/>
            <ConverterSpecIn  fileName="CICSPRGD.cbl" programName="BUP001"/>
            <ConverterSpecOut fileName="CICSPRGD.cbl" programName="BUP001"/>
            <WSBindSpec fileName="CICSPROG.wsbind" uri="/cics/services/CICSPROG" 
               logFileName="CICSPROG.log"
               mappingLevel="VENDOR" minimumRuntimeLevel="VENDOR"/>
         </XseSpec>
      </Operation>
   </EISService>
</EISProject>

Contained by

Contains

None

Attributes

Table 1 shows the attributes for WSBindSpec.
Table 1. Attribute Specifications for WSBindSpec
Fields Description
Attribute: arithExtend
Valid values: NO | YES
Required?: No
Default value: NO
Controls the maximum size of the pack decimal variable length that is mapping to the COBOL Language structure, If set to YES, it will use 31 digits for DECIMAL and INTEGER types. If set to NO (default), the number of digits remains at 18. This option is available at all mapping levels.
Attribute: businessPgmName
Valid values: See Description
Required?: No
Default value: See Description
Specifies the existing business program that CICS Web services runtime calls. This is the program that you are enabling for processing and/or producing XML messages to act as a Web service. This attribute is only meaningful for CICS native conversion and to specify target business program entry point for multiple operations in the compiled conversion.

The default value is: The Service name in the generated WSDL File truncated to 8 characters.
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 Web services 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 Web service 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 SOAP message. 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 or higher. 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 or higher. 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: contid
Valid values: See Description
Required?: No (Yes, if pgmint is
set to CHANNEL)
Default value: None (See Note 1)
 If the CICS application program (specified DriverSpec/businessPgmName or WSBindSpec/businessPgmName attribute of the element) communicates via a CHANNEL, specify the name of the CONTAINER expected by program.
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 it is set to DISABLED, CICS rejects the truncated application data and issues an error message.
Note: The ENABLED setting is only supported at mapping levels 3.0 and higher.
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 WSBindSpec 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 WSBindSpec is specified inside the EISService) then the valid values are:
  • UNUSED (default)

    or

  • PACKED15
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 or higher. 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 ".wsbind" (See Note 1).
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 Web services Assistant DFHLS2WS. 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 file The full description can be found in the CICS Transaction Server V 5.3 documentation, refer to:
Attribute: logFileName
Valid values: See Description
Required?: No
Default value: See Description
Specifies the name of the log file generated by the Web Services 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 | 4.0

Required?: No
Default value: 2.1 (See Note 1)  
 Specifies the version of the programmatic interface shared between CICS and the application (see Mapping levels for the CICS assistants). 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.
  • Mapping levels 1.0 to 4.0 are supported in CICS TS 5.2 and 5.3.

The use of old mapping levels is recommended only when regenerating the XML binding files for XML transformation resources that were previously deployed with an old mapping level (see CICS® Transaction Server for z/OS, Version 5 Release 2 Knowledge Center).

1.0
This is the CICS runtime default mapping level. For more information on mapping levels refer to CICS TS 4.1 documentation at: The CICS web services assistant
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 DFHLS2WS tab and the DFHWS2LS tab of the preferences.
  • It supports VARYING and VARYINGZ arrays,
Note: Mapping level 1.2 requires APAR PK23547.
2.0
Use this mapping level for CICS TS 3.2.

For more information on mapping levels refer to CICS TS 4.1 documentation at: The CICS web services assistant

2.1
Use this mapping level for CICS TS 3.2 and later with APAR PK59794 applied. At this level you can enable the following features:
  • INLINE-MAXOCCURS-LIMIT

    See the description of the Inline maxOccurs limit preference on the DFHWS2LS tab of the wizard (see Inline maxOccurs limit).

  • XML-ONLY (also called Pass-through XML)

    See the description of the Pass-through XML preference on the DFHWS2LS tab of the wizard (see Pass-through XML).

  • WSDL-NAMESPACE

    See the description of the WSDL namespace preference on the WSDL and XSD tab of the wizard (see WSDL namespace).

Support has been added for the XML schema element <xsd:any> and the data type xsd:anyType (for DFHWS2LS) (see Support for <xsd:any> and xsd:anyType).

2.2
Use this mapping level with a CICS 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.
4.0
Use this mapping level for CICS TS 5.2 and 5.3.
Attribute: mappingOverides
Valid values: See Description
Required?: No
Default value: See Description
Specifies whether the default behavior is overridden for the specified mapping level when generating language structures.

The options you can select are:

  • LESS-DUP-NAMES - For PL/I only. This parameter generates non-structural structure field names with _value at the end of the name to enable direct referencing to the field. The suffix _value is appended only when there is a name conflict between the structural name and non-structural name.
  • UNDERSCORES-AS-HYPHENS - For COBOL only. This parameter converts any underscores in the WSDL document to hyphens, rather than the character X, to improve the readability of the generated COBOL language structures. If any field name clashes occur, the fields are numbered to ensure they are unique.
Attribute: minimumRuntimeLevel
Valid values: MINIMUM |
1.0 | 1.1 | 1.2 |
2.0 | 2.1 | 4.0 | CURRENT
Required?: No
Default value: MINIMUM (See Note 1)
Specifies the minimum CICS runtime environment that the Web service 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.
1.0
The generated Web service binding file deploys successfully into CICS TS 3.1 region that does not have APARs PK15904 and PK23547 applied.
1.1
The generated Web service binding file deploys successfully into CICS TS 3.1 region that has at least APAR PK15904 applied.
1.2
The generated Web service binding file deploys successfully into CICS TS 3.1 region that has both APAR PK15904 and PK23547 applied.
Note: These APARs are not needed for CICS TS 3.2 and later.
2.0
The generated Web service binding file deploys successfully into CICS TS 3.2.
2.1
The generated Web service binding file deploys successfully into CICS TS 3.2 that has APAR PK59794 applied.
3.0
The generated Web service binding file deploys successfully into CICS TS 4.1
4.0
The generated Web service binding file deploys successfully into CICS TS 5.2 and 5.3
CURRENT
The generated Web service binding file deploys successfully into a CICS region at the highest available runtime level as the one you are using to generate the Web service binding file.
Attribute: nameTruncation
Valid values: RIGHT | LEFT
Required?: No
Default value: RIGHT
 Specifies how a generated field name is shortened if it is too long for use in the specified high-level language. This option is available at all mapping levels.
RIGHT
The field name is truncated from the right and a numeric suffix is added if necessary.
LEFT
The field name is truncated from the left and a numeric suffix is added if necessary.
Attribute: overwrite  
Valid values: true | false
Required?: No
Default value: true
 Specifies whether to overwrite the output file if it exists.
Attribute: pgmint
Valid values: 0 | 1| 2
Required?: No
Default value: 2
 Specify whether the CICS application program communicates via:
  • 0 - CHANNEL DESCRIPTION DOCUMENT

    Use CHANNEL DESCRIPTION DOCUMENT, when a Web service uses many containers in its application interface, must first create a channel description document to describe the containers. The channel description document is an XML document that conforms to a schema that is provided by CICS.

    CHANNEL DESCRIPTION DOCUMENT is only valid for (1) the CICS interpretive (bottom-up) conversion type AND (2) mapping level 3.0 and higher.

  • 1 - CHANNEL

    Use CHANNEL, when a Web service uses one container in its application interface.

  • 2 - DFHCOMMAREA

    This is the default.
Attribute: requestChannel
Valid values: See Description
Required?: No (Yes, if pgmint is
set to CHANNEL
DESCRIPTION DOCUMENT)
Default value: None

If the CICS application program (specified DriverSpec/businessPgmName or WSBindSpec/businessPgmName attribute of the element) communicates via a CHANNEL (multiple containers), specify the location of channel description document for the request.

This attribute is only valid for the CICS interpretive (bottom-up) 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.
Note: The language structure location(s) specified in the channel description document should be on the local file system (For example: <structure location=”c:\MyStructures\copybook.cpy”/>)
Attribute: responseChannel
Valid values: See Description
Required?: No  
Default value: None

If the CICS application program (specified DriverSpec/businessPgmName or WSBindSpec/businessPgmName attribute of the element) communicates via a CHANNEL (multiple containers), specify the location of channel description document for the response.

This attribute is only valid for the CICS interpretive (bottom-up) 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.
Note: The language structure location(s) specified in the channel description document should be on the local file system (For example: <structure location=”c:\MyStructures\copybook.cpy”/>)

If the application uses the same set of containers for the response as was used for the request, then specify the same value as the requestChannel
Attribute: service
Valid values: See Description
Required?: No
Default value: See Description
Use this parameter only when directed to do so by IBM® support.
Required Batch Options:
  • PlatformProperties.xml/CodegenPropertyArray/CodegenProperty
    • @name="CONVERSION_TYPE"
    • @value="interpretive"
  • ServiceSpecification.xml/EISService
Attribute: suppressGeneration
Valid values: true | false
Required?: No
Default value: false
 Indicates whether or not to suppress generation of the Web Services binding file (WSBind).
Attribute: synconreturn
Valid values: YES | NO
Required?: No
Default value: NO
 Specifies that the remote web service can issue a syncpoint. This attribute is equivalent to the SYNCONRETURN parameter of the CICS Web services assistant wizard pages DFHLS2WS and DFHWS2LS. The implication of setting this option to YES is that the remote task is committed at return. The remote task is classified as a separate unit of work (UOW). This means that if the remote web service updates a recoverable resource and then there is a failure after it returns, the update cannot be backed out. If this option is defaulted or set to NO and the remote web service issues a syncpoint, then the remote task fails with ABEND ADPL.
Attribute: transaction
Valid values: See Description
Required?: No
Default value: See Description
In a service provider, this parameter specifies the 1-4 character name of an alias transaction that can start the pipeline or run a user application to compose a HTTP response. The value of this parameter is used to define the TRANSACTION attribute of the URIMAP resource when it is created automatically using the PIPELINE scan command.

Acceptable characters: A-Z a-z 0-9 $
Attribute: uri
Valid values: See Description
Required?: No
Default value: See Description
 Desired local URI to for the Web service, for example, "/exampleApp/InquireSingle". Note: this is different that the location of the Web service for example, http://server:port[local URI]. If you do not specify this property it must be defined at install time during manual creation of the Web service resource definitions in CICS.
Attribute: userid
Valid values: See Description
Required?: No
Default value: See Description
In a service provider, this parameter specifies a 1-8 character user ID which can be used by any Web client. For an application-generated response or a Web service, the alias transaction is attached under this user ID. The value of this parameter is used to define the USERID attribute of the URIMAP resource when it is created automatically using the PIPELINE scan command.

Acceptable characters: A-Z a-z 0-9 $ @ #
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 (see Note 1)
Attribute: xmlOnly
Valid values: true | false
Required?: No
Default value: false
 If this attribute is set to true then CICS does not perform any transformations to the XML at all and instead requires that the application work with the contents of the DFHWS-BODY container directly. For a full description refer to: CICS® Transaction Server for z/OS, Version 5 Release 2 IBM Documentation
Note: The following WSBind default settings apply when multiple operations are present:
  • contid value: Service name in WSDL
  • fileName: WSDL file location and WSDL file name with .wsbind extension
  • mappingLevel: 1.2
  • minimumRuntimeLevel: 1.2
  • vendorConverterName: Service name in WSDL truncated to 8 characters

Related reference

CICS Web services assistant:
The CICS web services assistant

Example

<WSBindSpec fileName="CICSPROG.wsbind" uri="/cics/services/CICSPROG" 
         mappingLevel="VENDOR" logFileName="CICSPROG.log" ccsid="37" 
         minimumRuntimeLevel="VENDOR" userid="WEBUSER" transaction="WBTR">
</WSBindSpec>