Manual Web Services and CICS

Advanced Technical Support
Web Services and CICS Applications
2006 IBM Corporation
Web Services - Notes

This presentation will describe the Web Services capabilities provided by CICS Transaction Server Version 3.
Acknowledgements
The following are trademarks of International Business Machines Corporation in the United States, other countries, or both: IBM, CICS, CICS TS, CICS Transaction Server, DB2, MQ, OS/390, S/390, WebSphere, z/OS, zSeries, Parallel Sysplex. Java, and all Java-based trademarks and logos, are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Microsoft, Windows, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. Other company, product, and service names and logos may be trademarks or service marks of others.

This page intentionally left blank.
Session Agenda
Introduction to Web Services Architecture WSDL SOAP Application development scenarios Enablement styles Available tools CICS system configuration Resource definition CICS runtime support CICS 3.2 enhancements
Support for WSDL 2.0 Improved support for binary attachments CICS Support for WS-Trust
CICS Web Services Assistants

Mapping levels
Documentation Summary
5 2006 IBM Corporation

This page intentionally left blank.
Reasons to use Web Services in CICS

Transform Existing Applications Extend existing applications to new audiences and opportunities Exploit existing resources and skills Improve performance of existing workloads for faster response times and reduced costs Improve system management to enable management of more with less Simplify the development process to reduce application development costs and time to deployment

Customers are looking to redefine their applications quickly and effectively to meet their business demands. There is a need for rapid business process adaptation and reshaping. Application maintenance consuming 60-80% of IT budgets and staff turnover or retirement lessens individual programmer familiarity with existing systems, application maintenance efficiency is key driver. There is also a need to meet increasing development workloads. The growth in complexity of development platforms and integration needs will force organizations to turn away from code-centric development practices in exchange for more efficient development paradigms. They need better tooling to deliver more effective and efficient development processes. Industry adoption and proliferation of Web Services capabilities into development platforms and tools are making it easier for companies to adopt a service-based development approach. The need for richer than HTML experiences and disconnected operations will lead most companies to adopt multiple user interfaces delivery architectures. Finally, Because of recent pressures for cost reductions and market demand for better processes, we expect continued pressure from business executives to switch to new, business-differentiating activities. There will be a continued strong drive from business for process improvements.
Web Services Introduction

What is a Web Service?
A Web Service is an interface that:

Describes a collection of operations Is network accessible Uses standardized XML messaging
A Web Service is described:
Using standard, formal XML notation (service description) Covers all the details necessary to interact with the service

9
Message formats Transport protocols and location Independent of hardware or software platform Independent of programming language

A common program to program communication model built on existing and emerging standards, such as, HTTP, XML, SOAP, WSDL and UDDI. A Web service is an interface that describes a collection of operations that are network accessible through standardized XML messaging. A Web service is described using a standard, formal XML notion, called its service description. It covers all the details necessary to interact with the service, including message formats (that detail the operations), transport protocols and location. The interface hides the implementation details of the service, allowing it to be used independently of the hardware or software platform on which it is implemented and also independently of the programming language in which it is written. This allows and encourages Web Services-based applications to be loosely coupled, component-oriented, cross-technology implementations. Web Services fulfill a specific task or a set of tasks. They can be used alone or with other Web Services to carry out a complex aggregation or a business transaction.
10
The Web Services Stack

Business Process Execution Language (BPEL) WS-Reliable Messaging WS-Distributed Management UDDI Other protocols Other services Transports
11
Business Processes
WS-Coordination WS-Transactions
WS-Security family of specifications
Quality of Service
WSDL SOAP XML
WS-Policy
Description and Discovery Messaging and Encoding
Transport
The Web Services Base Technologies

Business Process Execution Language (BPEL) WS-Reliable Messaging WS-Distributed Management UDDI Other protocols Other services Transports
12
Business Processes
WS-Coordination WS-Transactions
WS-Security family of specifications
Quality of Service
WSDL SOAP XML
WS-Policy
Description and Discovery Messaging and Encoding
Transport
CICS and Web services standards

CICS TS V3.1 supports the following Web services standards
HTTP 1.0 and 1.1 * SOAP 1.1 and 1.2 Web Services Description Language (WSDL) Version 1.1 WS-I Basic Profile 1.1 WS-Coordination 1.0 WS-AtomicTransaction 1.0 WS-Security: SOAP Message Security
CICS TS V3.2 adds support for these Web services standards

Extensible Markup Language (XML) Version 1.0
XML Encryption Syntax and Processing XML-Signature Syntax and Processing XML-binary Optimized Packaging (XOP)
WS-I Simple SOAP Binding Profile Version 1.0 WS-I Basic Profile 1.1 (updated support) SOAP Message Transmission Optimization Mechanism (MTOM) SOAP 1.1 Binding for MTOM 1.0 Web Services Trust Language (WS-Trust) Web Services Description Language Version 2.0 WSDL 1.1 Binding Extension for SOAP 1.2
* WebSphere MQ can also be used as the transport layer
13

CICS TS V3 provides capabilities to enable CICS based applications to be integrated with a Service Oriented Architecture (SOA), enabling them to be exposed as Web Services. CICS has the ability to act as a Web Services service provider and service requestor which means it can be seen as a full participant in this B2B world. The infrastructure provided as part of CICS TS V3.1 includes a distributed transaction coordination capability compatible with the WS-AtomicTransaction specification. It will also include a WS-Security compatible implementation for securing SOAP messages. This will be delivered, via the service channel, at a later date WSDL 1.1 specification: SOAP 1.1 specification: SOAP 1.2 specification: XML 1.0 specification: http://www.w3.org/TR/wsdl http://www.w3.org/TR/2000/NOTE-SOAP-20000508/ http://www.w3.org/TR/soap12-part0/ http://www.w3.org/TR/2004/REC-xml-20040204/
14
Notes
Extensible Markup Language (XML) 1.0 is a subset of SGML. Its goal is to enable generic SGML to be served, received, and processed on the Web in the way that is now possible with HTML. XML has been designed for ease of implementation and for interoperability with both SGML and HTML. The specification for XML 1.0 and its errata is published by the World Wide Web Consortium (W3C) as a W3C Recommendation at http://www.w3.org/TR/REC-xml. XML Encryption Syntax and Processing specifies a process for encrypting data and representing the result in XML. The data may be arbitrary data (including an XML document), an XML element, or XML element content. The result of encrypting data is an XML Encryption element which contains or references the cipher data. XML Encryption Syntax and Processing is a recommendation of the World Wide Web Consortium (W3C) and is published at http://www.w3.org/TR/xmlenc-core. XML Signature Syntax and Processing specifies processing rules and syntax for XML digital signatures. XML digital signatures provide integrity, message authentication, and signer authentication services for data of any type, whether located within the XML that includes the signature or elsewhere. The specification for XML-Signature is published by World Wide Web Consortium (W3C) at http://www.w3.org/TR/xmldsig-core. XML binary Optimized Packaging (XOP) is one of a related pair of specifications that defines how to efficiently serialize XML Infosets that have certain types of content. XOP is used as an implementation of the MTOM specification, which defines the optimization of SOAP messages. As these two specifications are so closely linked, they are normally referred to as MTOM/XOP. The specification is published by the World Wide Web Consortium (W3C) as a W3C Recommendation at http://www.w3.org/TR/xop10/
Notes
WS-I Simple SOAP Binding Profile Version 1.0 (SSBP 1.0) is a set of non-proprietary Web services specifications, along with clarifications and amendments to those specifications which promote interoperability. The SSBP 1.0 is derived from the WS-I Basic Profile 1.0 requirements that relate to the serialization of the envelope and its representation in the message. WS-I Basic Profile 1.0 has now been split into two separately published profiles. These are: * WS-I Basic Profile Version 1.1 * WS-I Simple SOAP Binding Profile Version 1.0 Together, these two Profiles supersede the WS-I Basic Profile Version 1.0. The specification for SSBP 1.0 is published by the Web Services Interoperability Organization (WS-I), and can be found at http://www.ws-i.org/Profiles/SimpleSoapBindingProfile-1.0.html. The specification for WS-I BP 1.1 is published by the Web Services Interoperability Organization (WS-I), and can be found at http://www.ws-i.org/Profiles/BasicProfile-1.1.html. WS-I Basic Profile Version 1.1 (WS-I BP 1.1) is a set of non-proprietary Web services specifications, along with clarifications and amendments to those specifications, which together promote interoperability between different implementations of Web services. The WS-I BP 1.1 is derived from Basic Profile Version 1.0 by incorporating its published errata and separating out the requirements that relate to the serialization of envelopes and their representation in messages. These requirements are now part of the Simple SOAP Binding Profile Version 1.0. The specification for WS-I BP 1.1 is published by the Web Services Interoperability Organization (WS-I), and can be found at http://www.ws-i.org/Profiles/BasicProfile-1.1.html.
Notes
SOAP (Simple Object Access Protocol) is a lightweight, XML-based, protocol for exchange of information in a decentralized, distributed environment. The protocol consists of three parts: * An envelope that defines a framework for describing what is in a message and how to process it. * A set of encoding rules for expressing instances of application-defined data types. * A convention for representing remote procedure calls and responses. The specifications for SOAP are published by the World Wide Web Consortium (W3C). The specification for SOAP 1.1 is described as a note at http://www.w3.org/TR/SOAP. This specification has not been endorsed by the W3C, but forms the basis for the SOAP 1.2 specification. SOAP 1.2 is a W3C recommendation and is published in two parts: * Part 1: Messaging Framework is published at http://www.w3.org/TR/soap12-part1/ . * Part 2: Adjuncts is published at http://www.w3.org/TR/soap12-part2/. SOAP 1.1 Binding for MTOM 1.0 is a specification that describes how to use the SOAP Message Transmission Optimization Mechanism (MTOM) and XML-binary Optimized Packaging (XOP) specifications with SOAP 1.1. The SOAP 1.1 Binding for MTOM 1.0 specification is published as a formal submission by theWorld Wide Web Consortium (W3C) at http://www.w3.org/Submission/soap11mtom10/. SOAP Message Transmission Optimization Mechanism (MTOM) is one of a related pair of specifications that defines conceptually how to optimize the transmission and format of a SOAP message. The specification is published by the World Wide Web Consortium (W3C) as a W3C Recommendation at http://www.w3.org/TR/soap12-mtom/.
17
Notes
Web Services Security (WSS): SOAP Message Security is a set of enhancements to SOAP messaging that provides message integrity and confidentiality. WSS: SOAP Message Security is extensible, and can accommodate a variety of security models and encryption technologies. WSS: SOAP Message Security can be used in conjunction with other Web service extensions and application-specific protocols to satisfy a variety of security requirements. The specification is published by the Organization for the Advancement of Structured Information Standards (OASIS) at http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf. Web Services Trust Language (or WS-Trust) defines extensions that build on Web Services Security to provide a framework for requesting and issuing security tokens, and to broker trust relationships. WS-Trust describes: 1. Methods for issuing, renewing, and validating security tokens. 2. Ways to establish, access the presence of, and broker trust relationships. CICS supports the September 2006 version of the specification that is published at http://docs.oasis-open.org/wssx/ws-trust/200512/ws-trust-1.3-spec-cd-01.pdf
18
Notes
Web Services Atomic Transaction Version 1.0 (or WS-AtomicTransaction) is a protocol that defines the atomic transaction coordination type for transactions of a short duration. It is used with the extensible coordination framework described in the Web Services Coordination Version 1.0 (or WS-Coordination) specification. The WSAtomicTransaction specification and the WS-Coordination specification define protocols for short term transactions that enable transaction processing systems to interoperate in a Web services environment. Transactions that use WSAtomicTransaction have the ACID properties of atomicity, consistency, isolation, and durability. The specification for WS-AtomicTransaction is published at http://www.ibm.com/developerworks/library/specification/ws-tx/. Web Services Coordination Version 1.0 (or WS-Coordination) is an extensible framework for providing protocols that coordinate the actions of distributed applications. These coordination protocols are used to support a number of applications, including those that need to reach consistent agreement on the outcome of distributed activities. The framework enables an application service to create a context needed to propagate an activity to other services and to register for coordination protocols. The framework enables existing transaction processing, workflow, and other systems for coordination to hide their proprietary protocols and to operate in a heterogeneous environment. The specification for WS-Coordination is published at http://www.ibm.com/developerworks/library/specification/ws-tx/. Web Services Description Language (WSDL) is an XML format for describing network services as a set of endpoints operating on messages containing either document-oriented or procedure-oriented information. The operations and messages are described abstractly, and then bound to a concrete network protocol and message format to define an endpoint. Related concrete end points are combined into abstract endpoints (services). WSDL is extensible to allow the description of endpoints and their messages regardless of what message formats or network protocols are used to communicate. The WSDL 1.1 specification only defines bindings that describe how to use WSDL in conjunction with SOAP 1.1, HTTP GET and POST, and MIME. The specification for WSDL 1.1 is published by the World Wide Web Consortium (W3C) as a W3C Note at http://www.w3.org/TR/wsdl. WSDL 1.1 Binding Extension for SOAP 1.2 is a specification that defines the binding extensions that are required to indicate that Web service messages are bound to the SOAP 1.2 protocol. The aim of this specification is to provide functionality that is comparable with the binding for SOAP 1.1. This specification is published as a formal submission request by the World Wide Web Consortium (W3C) at http://www.w3.org/Submission/wsdl11soap12/.

Architecture Service provider
Owns the service Creates the WSDL Publishes the WSDL Processes requests
Find
WSDL, UDDI
Service Registry Publish

WSDL, UDDI
Service requester
Finds the service Binds to the service
Service Invokes the service using the WSDL Requester Bind
SOAP
Service Provider
Service Registry
Hosts the service description Optional for statically bound requesters
20

The Web services architecture is based upon interactions between three components: a service provider, a service requester, and an optional service registry. The Service Provider: This is the platform that hosts access to the service. The Service Requester: This is the application that is looking for and invoking or initiating an interaction with a service.. The Service Registry: The registry is a place where service providers publish their service descriptions, and where service requesters find them. The registry is an optional component of the Web services architecture.For statically bound service requesters a service provider can send the description directly to service requesters. Likewise, service requesters can obtain a service description from other sources besides a service registry, such as a local file or an FTP site. The interactions between the components involve the following operations: Publish: In order to be accessible, a service needs to publish its description such that the requester can subsequently find it. Where it is published can vary depending upon the requirements of the application. Find: The service requester uses a find operation to retrieve the service description from the registry. The find operation may be involved in two different lifecycle phases for the service requester: at design time in order to retrieve the services interface description for program development, and at runtime in order to retrieve the services binding and location description for invocation. Bind: The service requester uses the service description to connect to the service provider and interact with the web service implementation.
21

Web Services Description Language (WSDL) XML based language to describe an interface of a service WSDL comprises of
type portType message operation binding service port
abstract service interface definition
definition type
message
portType operation Input Output
how the service is implemented
binding
location of service
service
port
22

Web service descriptions are expressed in the XML application known as Web Service Description Language (WSDL). The structure of WSDL allows a service description to be partitioned into 2 parts. An abstract service interface definition that describes the interfaces of the service, and makes it possible to write programs that implement, and invoke, the service. A concrete service implementation definition that describes the location on the network (or endpoint) of the providers Web service, and other implementation specific details, and that makes it possible for a service requester to connect to the service provider. A WSDL document uses the following major elements. <types> A container for data type definitions using some type system (such as XML Schema). Defines the data types used within the message. The <types> element is not required when all messages consist of simple data types. <message> Specifies which XML data types are used to define the input and output parameters of an operation. <portType> Defines the set of operations supported by one or more endpoints. Within a <portType> element, each operation is described by an <operation> element. <operation> Specifies which XML messages can appear in the input and output data flows. An operation is comparable with a method signature in a programming language. <binding> Describes the protocol, data format, security and other attributes for a particular <portType> element. <port> Specifies the network address of an endpoint, and associates it with a <binding> element. <service> Defines the Web service as a collection of related endpoints. A <service> element contains one or more <port> elements.
Web Services Introduction What does the standardized XML message look like?
SOAP 1.1 or 1.2 message
Soap envelope <Envelope> consisting of:
Optional header element, <Header> Body element, <Body> Optional fault element <Fault>, may be added by service provider
SOAP Envelope SOAP Header Header Block Header Block
SOAP Body Body sub-element Body sub-element Fault element
24

SOAP is a protocol for the exchange of information in a distributed environment. SOAP messages are encoded as XML documents, and can be exchanged using a variety of underlying protocols. A SOAP message is encoded as an XML document, consisting of an <Envelope> element, which contains an optional <Header> element, and a mandatory <Body> element. The <fault> element, contained within the <Body> is used for reporting errors. The SOAP <Envelope> is the outermost element in every SOAP message, and contains two child elements, an optional <Header> and a mandatory <Body>. The SOAP <Header> is an optional element within the SOAP message, and is used to pass information in SOAP messages that is not application payload. The SOAP header allows features to be added to a SOAP message in a decentralized manner without prior agreement between the communicating parties. SOAP defines a few attributes that can be used to indicate who should deal with a feature and whether it is optional or mandatory. The SOAP <body>, a mandatory element, containing information intended for the ultimate recipient of the message. The SOAP <fault>, an element contained within the <body>, used for reporting errors.
25
Production and usage of WSDL

Requests from Service Requesters will be generated based on the information contained in WSDL IDE tools help generation of WSDL or application
IDE tools
WSDL location protocol operation message format

Input message
IDE tools
Service Requester
Output message
Service Provider
26

A web service provider needs to produce a WSDL document to describe the service which is being provided. This document is then published, using UDDI for example, or otherwise communicated to potential requesters of the service. Various tools may be used to assist with the generation of the WSDL. A web service requester needs to obtain the WSDL description of the service which it wants to use. Based on the WSDL, an application can be produced which will be able to request the services described in the WSDL. IDE Integrated Development Environment
27
Web Services Enablement

Bottom-up Top-down Meet in the middle
New service: WSDL
Existing service description WSDL
Existing service description WSDL
Generate
Generate
Map and Generate
Existing Business App (e.g. COBOL, C, C++, PLI)
New Business App (COBOL, C, C++, PLI)
Existing Business App (COBOL, C, C++, PLI)
28

There are three types of approaches in a Web service application development. With the top down approach, the development will start with a WSDL. Users will define the interface and created the WSDL, then create a Web service application based on that interface. The interface will be well defined but will need to create the whole service provider application. With the bottom up approach, an existing application will be used for the service provider application. The WSDL will be created based on the interface which the application uses. It is the easiest way to implement a Web service, but the interface to the service requester may not be very suitable. The meet in the middle approach is where there is an existing application, but using a better interface for the service requester. In this case, a wrapper program will be used to take the convert the existing application interface to and from the interface to the requester. It will have both advantages of the other approaches, with the suitable interface and low development cost.
29
Bottom up approach in CICS TS V3

An existing CICS application is to be exposed as a web service Language structure need to be extracted from the source code If the COMMAREA is very complex, it may be necessary to write a wrapper program to map the COMMAREA into a form which can be handled by the CICS tooling Use a CICS supplied batch procedure (DFHLS2WS) to convert language structure to WSDL
The language structure can be COBOL, PL/I, C or C++
Use Rational Developer for System z to convert language structure to WSDL

The language structure can be COBOL
Publish the generated WSDL, on UDDI for example A file called the WSBind file is also produced
30

For an existing CICS application, the COMMAREA will already be mapped by a language structure. The language structure is used as input to a CICS supplied utility which runs as a batch procedure. The procedure is called DFHLS2WS. This converts the supplied language structure into a WSDL document. WebSphere Developer for z/OS can also be used to convert a COBOL language structure into a WSDL document. A special file, the WSBind file, is also generated. This needs to be placed in an HFS directory where CICS will subsequently find it and install it. The WSDL so produced may then be published to the potential clients through the UDDI for example.
31
Top down approach in CICS TS V3 A supplied WSDL definition of a web service is to be implemented as a CICS application
Use CICS supplied batch procedure (DFHWS2LS) to convert the WSDL into a language structure. Use Rational Developer for System z to generate a COBOL language structure from the WSDL
Use the generated language structure in a CICS application program.
A file called the WSBind file is also produced.


The WSDL may be obtained from UDDI or by other means. The CICS tooling can handle DOC literal, RPC literal or wrapped Doc literal forms of WSDL as input. The outputs from the batch procedure are a WSBind file, as before, and a language structure which maps the data definitions from the WSDL into a structure in the specified high level programming language (COBOL, PL/I, C or C++).
33
Meet in the middle approach in CICS TS V3

Pure top down or bottom up will not be suitable in all situations In such situations, a wrapper program may provide a solution If the language structure uses data types not supported by the utility tools A wrapper program may be used to map COMMAREA to a supported data type When there are unnecessary fields in the language structure which you do not want to expose externally A wrapper program can be used to hide unnecessary fields Rational Developer for z/OS could be used to hide the fields When an existing piece of WSDL is to be used with an existing program The WSDL and the program may not match exactly. A wrapper program could perform some intermediate mappings
Pipeline
Conversion (SOAP COMMAREA)
Wrapper Program
Business Logic
34

Sometimes a pure top down or bottom up approach will not be satisfactory. The foil lists some circumstances when is might be desirable to have a wrapper program between the data mapping and the business logic. A wrapper program sits between the conversion operation and the business logic. It is then able to perform data manipulation either on the way in, on the way out or both ways.
35
CICS Resource Definitions

Define the transport
HTTP: TCPIPSERVICE for inbound requests WMQ: QLOCAL definition
Find the Web Service

URIMAP definition
Define the qualities of service

PIPELINE definition
Define the Web Service execution environment

WEBSERVICE definition
36

There are a number of interrelated resource definitions required to process a Web Service in CICS 31. A resource definition is required to define the transport. Both http and WebSphere MQSeries can be used as transports. For http, a CICS TCPIPSERVICE definition is required. For WMQ, a request queue must be defined with a QLOCAL definition. Next CICS must determine which Web Service is required. CICS 3.1 will use a URIMAP definition to map the incoming Universal Resource Identified (URI) to a specific WEBSERVICE definition. The associate PIPELINE definition is determined from the matching URIMAP definition. The PIPELINE definition is used to specify which processing nodes or message handlers are to operate on a Web Service request. The WEBSERVICE definition is used to specify how CICS is to execute the application. The WSBIND file, specified in the WEBSERVICE definition, is used to tell CICS which application program to execute, if a COMMAREA or CHANNEL is used and how CICS is to transform the message between the SOAP XML format and COMMAREA format.
37

TCPIPSERVICE definition
Required when CICS is a service provider and the transport is http
TCpipservice ==> GROup ==> DEscription ==> Urm ==> POrtnumber ==> 00000 1-65535 STatus ==> Open Open | Closed PRotocol ==> Iiop | Http | Eci | User TRansaction ==> Backlog ==> 00001 0-32767 TSqprefix ==> Ipaddress ==> SOcketclose ==> No No | 0-240000 (HHMMSS) Maxdatalen ==> 3-536870 SECURITY SSl ==> Yes Yes | No | Clientauth CErtificate ==> PRIvacy : Supported Notsupported | Required | Supported CIphers ==> 0504352F0A0903060102 AUthenticate ==> No No | Basic | Certificate | AUTORegister | AUTOMatic | ASserted ATtachsec ==> Verify DNS CONNECTION BALANCING DNsgroup ==> GRPcritical ==> No Local | Verify
No | Yes
38

A TCPIPSERVICE definition is required when CICS is the service provider and the chosen transport is HTTP. That is, the TCPIPSERVICE definition is only required for inbound requests. When a TCPIPSERVICE definition is used with protocol HTTP, the URIMAP definitions will be matched against the URI. If a match is found (it better be for Web Services) then some parameters will be taken from the URIMAP definition instead of the TCPIPSERVICE definition
39
CICS Resource Definitions WMQ definition

DEFINE
Required when CICS is a service provider Pick the target up from the RFH2 header if present, otherwise default to trigger data
QLOCAL(queuename) DESCR(description) PROCESS(processname) INITQ(initqueue) TRIGGER TRIGTYPE(FIRST) TRIGDATA(path part of URI) BOTHRESH(nnn) BOQNAME(requeuename)
40

A local WebSphere MQ queue definition is required when CICS is the service provider and the chosen transport is WMQ. For CICS as a service provider: Define A QLOCAL object that defines the local queue used to store the messages until they are processed A PROCESS object that specifies the CICS transaction CPIL that will process messages from the local queue Define the input queue
DEFINE QLOCAL ('queuename') DESCR ('description') PROCESS(processname) INITQ('initqueue') TRIGGER TRIGTYPE(FIRST) TRIGDATA('default target service') BOTHRESH(nnn) BOQNAME('requeuename')
queuename is the local queue name processname is the name of the process instance that identifies the application started by the queue manager when a trigger event occurs. The name should match that in the definition of the process object initqueue is the name of the initiation queue to be used (e.g. as specified in IQ= in CSQCPARM in INITPARM in SIT) default target service is the default target service to be used if not specified on the request, flows in RFH2 header. The target service is of the form '/string' and is used to match the path of a URIMAP definition. For example, '/ SOAP/test/test1'. Note that the first character must be '/', the next characters do not need to be SOAP. This is a difference from the SOAP for CICS feature, where TRIGDATA('SOAP/target_program' ) was specified.
41

URIMAP definition
Locates the Web Service and the Pipeline resources required to process the request
USAGE (PIPELINE) Specifies a Web Service request Matching the request URI HOST (www.mycics.co.uk) PATH (web_service_identifier) TCPIPSERVICE Restricts matching to a single port PIPELINE Names the Pipeline to process this request WEBSERVICE Names the associated Web Service for this request TRANSACTION Alias transaction for the Web Service
Urimap ==> Group ==> DEscription ==> STatus ==> Enabled USAge ==> Server UNIVERSAL RESOURCE IDENTIFIER SCheme ==> HTTP HOST ==> (Mixed Case) ==> PAth ==> (Mixed Case) ==> ==> ==> ==> ASSOCIATED CICS RESOURCES TCpipservice ==> Analyzer ==> No COnverter ==> TRansaction ==> PRogram ==> PIpeline ==> Webservice ==>
Enabled | Disabled Server | Client | Pipeline HTTP | HTTPS
No | Yes
(Mixed Case)
42

The URIMAP definition is used to match a URI to a WEBSERVICE definition and a PIPELINE definition. You should have a unique URI for each Web Service that you want to use in CICS. The parameters that apply to a Web Service form of the URIMAP are: USAGE (PIPELINE): This indicates that the URIMAP definition is applicable to a web service and that the PIPELINE and WEBSERVICE parameters must be specified. The SCHEME, HOST and PATH values must be specified to allow matching of the URI. A URI, such as,http://www.mycics.co.uk/webservice would be decomposed to SCHEME (http), HOST (www.mycics.co.uk) and PATH (webservice) TCPIPSERVICE is optional on the URIMAP definition for USAGE (PIPELINE). If a named TCPIPSERVICE is specified then only requests from that specific port will be matched against this URIMAP definition. The PIPELINE parameter names an installed PIPELINE resource which will be used to determine the processing nodes or message handlers that will be invoked for this Web Service request. The WEBSERVICE parameter names an installed WEBSERVICE requests that defines the execution environment that lets a CICS application program operate as a Web service provider or requester. The TRANSACTION parameter specifies the 1-4 character name of an alias transaction that is to be used to run the user application that composes a response to the web service request.

PIPELINE definition Defines the processing nodes for a web service request
Different pipelines for:
Requester and provider
PIPELINE ==> Group Description Status Configfile (Mixed Case) ==> ==> ==> Enabled ==> ==> ==> ==> ==> Shelf ==> (Mixed Case) ==> ==> ==> ==> Wsdir ==> (Mixed Case) ==> ==> ==> ==>
Enabled | Disabled
CONFIGFILE
HFS file that contains information about the message handlers that will act on a service request and on the response
SHELF
HFS directory for CICS use
WSDIR
Pickup directory for WS Bind files
44

A PIPELINE resource definition is used when a CICS application is in the role of a Web service provider or requester. It provides information about the processing nodes which will act on a service request and on the response. Typically, a single PIPELINE definition defines an infrastructure that can be used by many applications. There will be separate configuration files for CICS applications acting as a service provider and service requester. The information about the processing nodes is supplied indirectly: the PIPELINE specifies the name of an HFS configuration file (CONFIGFILE) which contains an XML description of the nodes and their configuration. The SHELF is an HFS directory where CICS will copy information about installed Web Services. CICS regions into which the PIPELINE definition is installed must have full permissions to the shelf directory--read, write, and the ability to create subdirectories. A single shelf directory may be shared by multiple CICS regions and by multiple PIPELINE definitions. Within a shelf directory, each CICS region uses a separate subdirectory to keep its files separate from those of other CICS regions. Within each region's directory, each PIPELINE uses a separate subdirectory. After a CICS region performs a cold or initial start, it deletes its subdirectories from the shelf before trying to use the shelf. You should not attempt to modify the contents of a shelf that is referred to by an installed PIPELINE definition. If you do, the effects are unpredictable The Web service binding directory (WSDIR) contains Web service binding files that are associated with a PIPELINE, and that are to be installed automatically by the CICS scanning mechanism. When the PIPELINE definition is installed, CICS scans the directory and automatically installs any Web service binding files it finds there. Note that this happens regardless of whether the PIPELINE is installed in enabled or disabled state. A CEMT PERFORM PIPELINE SCAN command can be used to force CICS to scan the Web Service binding directory. An inbound Web service request (that is, a request by which a client invokes a Web service in CICS) is associated with a PIPELINE resource by the URIMAP resource. The URIMAP identifies the PIPELINE resource that applies to the URI associated with the request; the PIPELINE specifies the processing that is to be performed on the message.
45

Pipeline configuration file XML file that describes:
The mandatory <service> and optional <transport> elements The sequence of message handlers to be invoked
Different applications will require different configuration files

Service provider Service requester SOAP 1.1 SOAP 1.2 User message handlers
e.g. Extract USERID from the message
46

The Pipeline configuration file, named in a PIPELINE resource definition, is used to describe the series of message handlers (i.e. the pipeline) to process the request. The configuration file is an XML document, stored in HFS and can be edited with any XML editor. The configuration file will contain mandatory <service> and optional <transport> elements along with application handler <apphandler> and a service parameter list <service_parameter_list>. Different applications will require different configuration files. There are different pipeline configurations necessary for a service provider and service requester as well as different configurations for processing SOAP 1.1 and 1.2 messages. CICS provides the configuration files necessary for CICS to function as both a service requester and a service provider handling both SOAP 1.1 and 1.2 messages. The configuration file can also be used to add your own user message handlers. An example would be a user message handler to extract user identification from the message to determine which USERID and transaction id should be used to process the message.
47

Pipeline XML configuration for a service provider
<?xml version="1.0" encoding="UTF-8"?> <provider_pipeline xmlns="http://www.ibm.com/software/htp/cics/pipeline" .....xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" .....xsi:schemaLocation=http://www.ibm.com/software/htp/cics/pipel ine provider.xsd> <service> <terminal_handler> <cics_soap_1.1_handler/> </terminal_handler> </service> <apphandler>DFHPITP</apphandler> </provider_pipeline>

The simplest provider pipeline configuration: A single CICS supplied SOAP 1.1 handler as the terminal handler to parse the soap envelope. AppHandler is specified as DFHPITP. This is the CICS module to be invoked by the pipeline. The CICS Infocenter gives several examples of configuration files which are more complex than the one shown in the foil.
49

WEBSERVICE definition Defines the application specific details for a web service request
Defines the execution environment for Web Service application
WEBSERVICE ==> Group ==> Description ==> Pipeline ==> (Mixed Case) ==> ==> ==> ==> WSBIND ==> (Mixed Case) ==> ==> ==> ==> WSDLFILE ==> (Mixed Case) ==> ==> ==> VALIDATION ==>
PIPELINE
Name of the pipeline where this WEBSERVICE is to be installed
WSBIND
HFS name of the WS Binding file
WSDLFILE
HFS name of the WSDL file
NO NO|YES
VALIDATION
Run time SOAP message validation against WSDL schema
50

A WEBSERVICE resource defines the execution environment that lets a CICS application program operate as a Web service provider or requester. The Web service interaction in which the CICS application participates uses SOAP messaging, and is formally described with Web service description language (WSDL). The execution environment contains three components that are specified in the WEBSERVICE attributes: A pipeline A Web service binding file A Web service description Although CICS provides the usual resource definition mechanisms for creating WEBSERVICE resources, and installing them in your CICS region, there is an alternative strategy which you can use. You can use the scanning mechanism to install WEBSERVICE resources in your running CICS region. Validation: Specifies whether full validation of SOAP messages against the corresponding schema in the Web service description should be performed at run-time. Validating a SOAP message against its schema incurs considerable processing overhead, and you should normally specify VALIDATION(NO). Full validation ensures that all SOAP messages which are sent and received are valid XML with respect to the XML schema. If VALIDATION(NO) is specified, sufficient validation is performed to ensure that the message contains well-formed XML.
CICS as a service provider

TCPIPSERVICE
SOAP message
CICS TS V3
CPIH
Pipeline
CSOL
Service Requester
CWXN
URIMAP matching
handlers
HFS
pipeline config WSDL
CICS provided utility
URIMAP handlers dynamic install handlers PIPELINE data mapping dynamic install Business Logic
WSBind WEBSERVICE Language structure

52
CICS as a service requester

User Transaction
Business Logic data mapping Pipeline WEBSERVICE dynamic install PIPELINE handlers pipeline config handlers WSDL
CICS TS V3
Language structure
HFS
WSBind
CICS provided utility
handlers Service Provider

SOAP message
53
CICS usage of the WSBind file

CICS as a service provider
CICS Web services Service Requester pipeline
SOAP body
Data mapping
HLL data structure
business logic
WEBSERVICE resource
WSDL
WSBind file
CICS

CICS Web services
business logic HLL data structure
Data mapping
SOAP body
pipeline
Service Provider
WSDL
WSBind file
WEBSERVICE resource
CICS

This diagram shows the usage of the WSBind file and WEBSERVICE resource in the runtime. When the SOAP message arrives, the data mapping component in the pipeline will use the information from the WSBind file and convert the SOAP message into a language structure. When the message is converted it will use the information in the WEBSERVICE resource and call the target application. When the target application returns with a response language structure, it will convert it back into a SOAP message. It is mostly the same when CICS is a service requester. The service requester will invoke the Web service processing. The data mapping component will convert the language structure into a SOAP message an run the outbound pipeline. The pipeline will use the information in the WEBSERVICE resource and send the SOAP message outbound. When the response is received, the data mapping component will convert the response SOAP message back into a language structure and pass it back to the service requester program. The WSDL file is optional. It is only needed if a validation of the SOAP message is required.
55
Application Programming Interfaces

Invoking a Web Service from a CICS application program
EXEC CICS INVOKE WEBSERVICE ( ) CHANNEL ( ) URI ( ) OPERATION ( ) WEBSERVICE: name of the Web Service to be invoked CHANNEL: name of the channel containing data to be passed to the Web Service (DFHWS-DATA container) URI: Universal Resource Identifier of the Web Service (optional) OPERATION: name of the operation to be invoked

The purpose of the command is to invoke the web service named and pass the channel into which the relevant containers have been put. The container DFHWS-DATA must be created by the requesting application before the INVOKE WEBSERVICE command is issued. The same container, DFHWS-DATA, will hold the response, if any, from the Web Service.
57
Application Programming Interfaces

If a program needs to issue a SOAP fault message
EXEC CICS SOAPFAULT CREATE EXEC CICS SOAPFAULT ADD EXEC CICS SOAPFAULT DELETE
Using the API takes care of whether the SOAP message is SOAP 1.1 or SOAP 1.2 automatically
58

Here is the syntax diagram for SOAPFAULT CREATE. Full details of all the commands can be found in the CICS Infocenter.
59
Support for WSDL 2.0

WSDL 2.0 is a Candidate Recommendation with the W3C CICS conditionally complies with WSDL 2.0 Mandatory requirements Only the message exchange patterns in-only, in-out, robust in-only, and in-optional-out may be used in the WSDL Only one Endpoint is allowed for each Service There must be at least one Operation Endpoints may only be specified with a URI There must be a SOAP binding The XML schema type must be used
60
Notes
The WSDL 2.0 specification is a W3C Candidate Recommendation. If changes are made to this specification as it progresses to a W3C Recommendation then there may be delay or change to the implementation of WSDL 2.0 support in CICS TS V3.2. This chart lists the support CICS 3.2 provides for WSDL 2.0.
61

Aspects that are tolerated Features, Extension, and Properties are ignored. The following HTTP binding properties are ignored:
whttp:location whttp:header whttp:transferCodingDefault whttp:transferCoding whttp:cookies whttp:authenticationType whttp:authenticationRealmAspects
SOAP header information is ignored by DFHWS2LS
62
Notes
This chart lists the WSDL 2.0 attributes which are tolerated, that is, ignored by the CICS Web Service Assistants. SOAP header information is ignored by DFHWS2LS. However, you can add your own message handlers to the pipeline to create and process the required SOAP header information for inbound and outbound messages.
63

Aspects that are not supported The #any and #other message content models The out-only, robust-out-only, out-in and out-optional-in message exchange patterns WS-Addressing for Endpoints HTTP GET is not supported Adding required SOAP headers to the SOAP messages sent by CICS is not supported in the Web services assistant tooling. However, you can configure this manually in the pipeline CICS does not ensure that required or optional SOAP Modules and features are used at run time
64
Notes
This chart lists the WSDL 2.0 attributes which are not supported by CICS 3.2. HTTP GET is not supported. This is defined using the soap-response message exchange pattern in the WSDL document. If your WSDL defines this message exchange pattern, DFHWS2LS issues an error message.
65

Message exchange patterns supported In-Only
CICS as the provider
CICS will receive a message and send no response
CICS as the requester

CICS application will send a message and expect no response
In-out
CICS will receive a message and respond with a normal response or fault

CICS application will send a message and expect a normal response of fault
66
Notes
In-only with CICS as provider This pattern is where CICS receives a message and must not return anything to the requester even if something goes wrong. This pattern is supported already and will continue to be supported in the same way. CICS Web Service support puts the DFHNORESPONSE container into the SOAP handler channel to indicate that the pipeline must not send anything to the requester. In-only with CICS as requester This pattern is where CICS as a requester of service will send a message to a service provider and receive no response. This situation is supported already. The task sending the message knows that no response is to expected, so it will not wait for one. In-out with CICS as provider In this pattern, CICS will receive a message from a requester and will respond with either a normal response or with a fault message. This is a normal flow of messages for a web service and very much in the standard CICS application pattern. It is already supported and will continue to be so. In-Out with CICS as requester In this pattern, CICS will send a message to a service provider and will receive a response, which may either be a normal response or a fault message. Again, this is a natural set of messages for a CICS application. The pattern is already supported and will continue to be so.
67

Message exchange patterns supported Robust in-only
CICS will receive a message and respond only if an error occurs

CICS application will send a message and expect a response only if an error occurs > New timeout specification on the PIPELINE definition
In-optional-out
CICS will receive a message and may respond with > A normal response > An error response > Nothing (no response)

CICS application will send a message and expect: > A normal response > An error response > Nothing (no response)
68
Notes
Robust in-only with CICS as provider CICS as the service provider will receive a message from the requester. CICS only needs to respond if an error occurs. If an error occurs in the pipeline, a SOAP fault will be sent back to the requester. Robust in-only with CICS as requester If CICS is the service requester in a MEP where a response of some sort may or may not be received, then a timeout needs to be specified to define how long CICS is to wait for any possible response. A new timeout parameter has been added to the PIPELINE resource. The value specified is stored in binary form in a new container called DFHWS-RESPWAIT. The value specifies the timeout value to use in seconds. This is so as to allow the value to be interrogated and perhaps changed by handlers in the PIPELINE if desired. In-optional-out CICS as provider CICS as a provider with this MEP will receive a message from the requester and then may send a normal response, may send an error response or may send nothing back to the requester. Which option will occur is not known until runtime. The application program will need to indicate to DFHPITL that it does not intend to send a response by deleting the DFHWS-DATA container from the channel. In-optional-out CICS as requester If CICS is the requester of service, it will send a message to the service provider. The provider may respond with a normal response, an error response or never respond at all. The situation is very similar to that for the robust in-only pattern with CICS as the requester. The question is, how long does CICS wait for the optional response from the provider? The solution will be to use the timeout value again for this situation.

EXEC CICS INVOKE WEBSERVICE command New response values INVREQ (Robust in-only when CICS is the requester)
RESP2=6
Web Service has returned a fault in response to a request
TIMEDOUT (In-optional-out or In-out when CICS is the requester)

RESP2=1
Web Service request has timed out > Probably successful
RESP2=2
Web service request has timed out > Probably unsuccessful
New RESPWAIT attribute on PIPELINE resource definition

Notes
Robust-in-Only The Robust-in-only MEP when CICS is the service requester is of interest. CICS will send a SOAP message to an external service provider which under normal circumstances will not respond. However, if an error occurs, the service provider will respond with an error message. For this MEP, the wait for a response timing out means that the service provider has not sent an error message back. A response occurring before the wait times out means that the request has failed. If a response is returned when the MEP is robust-in-only, the RESP code needs to be set to INVREQ with a RESP2 code of 6: A Web Service has returned a SOAP fault in response to a request from CICS. If a response is not returned and a timeout occurs, this means that the request was probably successful. A RESP code of 0 is returned to the application. This allows the application to continue normally without having to handle the timeout situation, which will probably be the normal case for this MEP. In-optional-out The in-optional-out MEP when CICS is the service requester is very similar to the robust-in-only situation in that CICS has no a prior knowledge as to whether to expect any response from the service provider. If the wait for a response times out, this may mean that the service provider chose not to respond. If the service provider does respond, then it may be either a normal response message or a SOAP fault. In-out when CICS is the requestor CICS will send a message to a service provider and will receive a response, which may either be a normal response or a fault message. If a request times out and the MEP is in-optional-out or in-out when CICS is the requestor then a RESP code of TIMEDOUT is returned. The RESP2 value indicates the probably success of the request. RESP2=1 Web Service request has timed out. Probably successful RESP2=2 Web service request has timed out. Probably unsuccessful The RESPWAIT attribute on the PIPELINE definition enables you to control the time that an application program waits for a response message from a remote web service. RESPWAIT(number) Specifies the number of seconds that an application program should wait for a response message from a remote Web service. The value can range from 0 to 9999 seconds. If you do not specify a value for this attribute, the default timeout value of the transport protocol is used. The default timeout value for HTTP is 10 seconds. The default timeout value for MQ is 60 seconds.

INQ PIPELINE New information returned
SOAPlevel(1.1 ) Mode(Provider) Respwait()
SET PIPELINE RESPWAIT may be changed
INQ WEBSERVICE New information returned

CCSID(00037) Mappinglevel(2.0) Minruntimlvl(2.0)
Notes
There are new options for the INQUIRE PIPELINE command. MODE(cvda): Returns the operating mode of the pipeline. CVDA values are: PROVIDER - CICS is using the pipeline as a service provider of Web services. REQUESTER - CICS is using the pipeline as a service requester of Web services. UNKNOWN - The operating mode of the pipeline cannot be determined. RESPWAIT(data-area): Returns the number of seconds that an application program waits for an optional response message from a remote Web service. If no value is set, the default timeout value of the transport protocol is being used. The default timeout value for HTTP is 10 seconds. The default timeout value for MQ is 60 seconds. SOAPLEVEL(data-area): Returns an eight byte character string of the SOAP level that is used in the PIPELINE. The value of the SOAP level is 1.1 or 1.2. If the pipeline is not being used for SOAP messages, a value of NOTSOAP is returned. SOAPRNUM(data-area): Returns a fullword binary value of the release number for the SOAP level that is used in the PIPELINE. The value of the release number is 1 or 2. SOAPVNUM(data-area): Returns a fullword binary value of the version number for the SOAP level that is used in the PIPELINE. The value of the version number is 1. The following new option has been added to the SET PIPELINE command. RESPWAIT(data-area): Specifies the number of seconds that an application program should wait for an optional response message from a remote Web service. The value can range from 0 to 9999 seconds. If you do not specify a value, the default timeout value of the transport protocol is used. The default timeout value for HTTP is 10 seconds. The default timeout value for MQ is 60 seconds.
Notes
There are new options for the INQUIRE WEBSERVICE command. CCSID(data-area): Returns the CCSID that is used to encode data between the application program and the SOAP message at run time. This value is set using the optional CCSID parameter in the Web services assistant when the Web service binding file was generated. If the data-area is 0, the default CCSID for the CICS region that is specified by the LOCALCCSID system initialization parameter is used. MAPPINGLEVEL(data-area): Returns an eight byte character string of the mapping level that is used to convert data between language structures and Web service description (WSDL) documents. The value of the mapping level is 1.0, 1.1, 1.2 or 2.0. MAPPINGRNUM(data-area): Returns a fullword binary value of the release number for the mapping level that is used to convert data between language structures and Web service description (WSDL) documents. The value of the release number is 0, 1, or 2. MAPPINGVNUM(data-area): Returns a fullword binary value of the version number for the mapping level that is used to convert data between language structures and Web service description (WSDL) documents. The value of the version number is 1 or 2. MINRUNLEVEL(data-area): Returns an eight byte character string of the minimum runtime level that is required to run the Web service in CICS. The value of the runtime level is 1.0, 1.1, 1.2 or 2.0. MINRUNRNUM(data-area): Returns a fullword binary value of the release number for the minimum runtime level that is required to run the Web service in CICS. The value of the release number is 0, 1, or 2. MINRUNVNUM(data-area): Returns a fullword binary value of the version number for the minimum runtime level that is required to run the Web service in CICS. The value of the version number is 1 or 2. .

New Container for WSDL 2.0 processing DFHWS-MEP
Contains a value for the message exchange pattern
1 In-Only 2 In-Out 4 Robust-In-Only 8 In-Optional-Out
75
Notes
DFHWS-MEP is a container of DATATYPE(BIT) that holds a representative value for the message exchange pattern of an inbound or outbound SOAP 1.2 message. CICS supports four message exchange patterns for both service requesters and service providers. The message exchange pattern is defined in the WSDL 2.0 document for the Web service and determines whether CICS should respond as the provider, and if CICS should expect a response from an external provider. In requester mode, the time that CICS waits for a response is configured using the PIPELINE resource. Use this container to determine the MEP of the request message. Table 1. Values that can appear in container DFHWS-MEP Value 1 2 4 8 MEP In-Only In-Out Robust-In-Only In-Optional-Out URI http://www.w3.org/2006/01/wsdl/in-only http://www.w3.org/2006/01/wsdl/in-out http://www.w3.org/2006/01/wsdl/robust-in-only http://www.w3.org/2006/01/wsdl/in-opt-out
76
Improved Support for Binary Attachments

In standard SOAP messages:
Binary objects are base64 encoded Included in the message body Significantly increases their size Can impact message parsing time Can impact transmission time
MTOM/XOP provides a solution to this problem The MTOM specification

Defines a method for optimizing SOAP messages Separates out binary data Sends it in separate binary attachments using a MIME Multipart/Related message
The XOP specification

Defines an implementation for optimizing XML messages Uses binary attachments in a packaging format Includes but is not limited to MIME messages
77
Notes
In standard SOAP messages, binary objects are base64 encoded and included in the message body. This significantly increases their size, and for very large binary objects, this can impact transmission time. Implementing MTOM/XOP provides a solution to this problem. The SOAP Message Transmission Optimization Mechanism (MTOM) and XML-binary Optimized Packaging (XOP) specifications, often referred to as MTOM/XOP, define a method for optimizing the transmission of large base64binary data objects within SOAP messages. - The MTOM specification conceptually defines a method for optimizing SOAP messages by separating out binary data, that would otherwise be base64 encoded, and sending it in separate binary attachments using a MIME Multipart/Related message. This type of MIME message is called an MTOM message. Sending the data in binary format significantly reduces its size, thus optimizing the transmission of the SOAP message. - The XOP specification defines an implementation for optimizing XML messages using binary attachments in a packaging format that includes but is not limited to MIME messages. The size of the base64binary data is significantly reduced because the attachments are encoded in binary format. The XML in the SOAP message is then converted to XOP format by replacing the base64binary data with a special <xop:Include> element that references the relevant MIME attachment using a URI.

CICS implements MTOM/XOP support
In both the requester and provider pipelines
New MTOM/XOP configuration definitions
New modes of operation in the pipeline

Direct mode
Binary attachments associated with an MTOM message
Passed in containers through the pipeline and handled directly by the application handler Inbound messages > Application handler passes the binary attachments to the application program without needing to perform any data conversion Outbound messages > XOP enabled applications can pass binary attachments from the application program to the pipeline without any data conversion
Compatibility mode
XOP document contained in inbound MTOM messages
Converted into a SOAP message Associated binary attachments are converted into base64binary data..
Outbound SOAP messages are converted into an MTOM message after all other processing has taken place
Each binary object has to be converted from a base64 encoding in the pipeline
WS-Security and WSDL Validation use compatibility mode

Notes
CICS implements support for these specifications in both requester and provider pipelines. As an alternative to including the base64binary data directly in the SOAP message, CICS applications that are deployed as Web service providers or requesters can use this support to send and receive MTOM messages with binary attachments. You can configure this support by using additional options in the pipeline configuration file. There are certain scenarios where CICS cannot support the XOP document format in MTOM messages directly. For example, the Web Services security functionality and Web services validation cannot parse the <xop:Include> elements in the XOP document. Therefore, two modes of support are provided in the pipeline to handle XOP documents and any associated binary attachments. If the application handler program is capable of supporting XOP documents, such as the standard handlers that are provided when you deploy a Web service using the Web services assistant, then CICS performs XOP processing in direct mode. If you are using a different application handler in the pipeline that is not capable of handling XOP documents, all XOP processing is performed in compatibility mode. If you are using the Web Services Security functionality or are testing with validation switched on, all XOP processing is performed in compatibility mode even if you have specified direct mode in the pipeline configuration file.

CICS MTOM/XOP restrictions If web services security is enabled along with MTOM support
Then the pipeline will handle MTOM messages in compatibility mode
If web services validation is activated

CICS will change to compatibility mode from direct mode
DFHLS2WS does not generate fields eligible for XOP optimization

Solution
Run DFHLS2WS, then run DFHWS2LS on the generated WSDL
81
Notes
The support for MTOM/XOP in CICS is subject to the following restrictions: - If you enable the MTOM handler program in the pipeline configuration file, and also enable Web services security, the pipeline only supports the handling of MTOM messages in compatibility mode. - If you switch on Web service validation, CICS automatically changes from direct mode to compatibility mode for all XOP processing. This is because the validation cannot handle the contents of XOP documents. When you are using DFHWS2LS and a mapping level of at least 1.2, the generated language structures include base64Binary fields. MTOM/XOP cannot be used when an existing application is Web service enabled using DFHLS2WS. This is because only XML base64Binary fields are eligible for XOP optimization, and DFHLS2WS never generates these field types. If you have an application that you want to enable as a Web service and support MTOM/XOP, you should run DFHLS2WS first to generate the WSDL and then run DFHWS2LS on the generated WSDL to get a Web service binding file that interprets the fields as base64Binary data.
82

CICS MTOM/XOP restrictions The XOP specification states:
There should be no white space in the base64binary data. An application program that wants to use XOP processing must use the canonical form.
If the base64binary data in an outbound message does contain white space

CICS does not convert the data to a binary attachment
The contentType attribute must be present on:

Base64 binary fields for XOP processing to occur in compatibility mode on outbound messages
The contentType attribute must not be present on hexBinary fields. CICS will not use MTOM/XOP for fields less than 1500 bytes
Notes
The support for MTOM/XOP in CICS is subject to the following restrictions: - As stated in the XOP specification, there should be no white space in the base64binary data. Any application programs that produce base64binary data that want to use XOP processing must use the canonical form. If the base64binary data in an outbound message does contain white space, CICS does not convert the data to a binary attachment. When base64binary data is generated by CICS, the fields are provided in canonical form and therefore contain no white space. - The contentType attribute must be present on base64binary fields for XOP processing to occur in compatibility mode on outbound messages. The contentType attribute must not be present on hexBinary fields.
84

Configuring MTOM/XOP support Add a <cics_mtom_handler> element
<cics_mtom_handler/> Handler must be first one when CICS is the provider Handler must be last one when CICS is the requester
Optionally, add configuration options

A configuration container is required
<cics_mtom_handler> <dfhmtom_configuration version="1"> </dfhmtom_configuration> </cics_mtom_handler>
Notes
To configure CICS for MTOM/XOP processing of MTOM messages, you must add the MTOM handler to your pipeline configuration files. Before performing this task, you must identify or create the pipeline configuration files to which you will add configuration information for MTOM/XOP. In a provider pipeline, this handler should be invoked before any other service handlers, as it needs to unpackage the inbound MTOM message before other handlers process it. It will also then be invoked as the last handler for the response message, to package an MTOM message to send to the Web service requester. In a requester pipeline, this handler should be invoked after any other service handlers, so that the outbound request message is not converted into MTOM format until all other handlers have processed it. It will then also be invoked as the first handler for the inbound response message to unpackage the MTOM message before other handlers process it and return to the requesting program. Add a <cics_mtom_handler> element to your pipeline. Code the following elements: <cics_mtom_handler> <dfhmtom_configuration version="1"> </dfhmtom_configuration> </cics_mtom_handler> The <cics_mtom_handler_configuration> element is a container for the other elements in the configuration. If you want to accept the default settings for MTOM/XOP processing, you can specify an empty element as follows: <cics_mtom_handler/>
86

Configuring MTOM/XOP support Configure MTOM options
send_mtom
no > MTOM is not enabled for outbound SOAP messages same > In service provider mode, MTOM is enabled for SOAP response messages whenever the requester uses MTOM > In service requester mode, specifying this value is the same as yes yes > MTOM is enabled for all valid outbound SOAP messages
send_when_no_xop
no > MTOM is only used when binary attachments are being sent with the message > Has no effect when send_mtom=no. yes > MTOM is used for outbound SOAP messages > Even when there are no binary attachments in the message
87
Improved Support for Binary Attachments Configuring MTOM/XOP support

Configure XOP options
apphandler_support
no > The application handler cannot handle XOP documents directly > Default value if the <apphandler> element does not specify DFHPITP yes > The application handler can handle XOP documents > Default value if the <apphandler> element specifies DFHPITP > Direct mode is used in the pipeline to handle any inbound or outbound messages that are received or sent in MTOM format
Notes
apphandler_supports_xop In provider mode, specifies if the application handler is capable of handling XOP documents in direct mode: no: The application handler cannot handle XOP documents directly. This is the default value if the <apphandler> element does not specify DFHPITP. Compatibility mode is used in the pipeline to handle any inbound or outbound messages that are received or sent in MTOM format. yes: The application handler can handle XOP documents. This is the default value if the <apphandler> element specifies DFHPITP. Direct mode is used in the pipeline to handle any inbound or outbound messages that are received or sent in MTOM format. This is subject to restrictions at run time. For example, if you have specified WS-Security related elements in the pipeline configuration file, the MTOM handler determines that the pipeline should use compatibility mode rather than direct mode for processing XOP documents. In requester mode, specifies if service requester applications use the CICS Web services support to create and handle XOP documents in direct mode. no: Service requester applications do not use the CICS Web services support. Specify this value if your requester application links to DFHPIRT to drive the pipeline, and is therefore not capable of creating and handling XOP documents in direct mode. yes: Service requester applications do use the CICS Web services support. Specify this value if your requester application uses the EXEC CICS INVOKE WEBSERVICE command.

Configure MIME options
content_id_domain
Specifies the domain name that should be used when generating MIME content-ID values > Used to identify binary attachments Syntax to use is domain.name. > The name should be a valid internet host name > Should be unique to the CICS system where the pipeline is installed > Not checked by CICS > If this element is omitted, the current host name is used.

An example pipeline (CICS as the provider)
<cics_mtom_handler> <dfhmtom_configuration version="1"> <mtom_options send_mtom="same" send_when_no_xop="no" /> <xop_options apphandler_supports_xop="yes" /> <mime_options content_id_domain="example.org" /> </dfhmtom_configuration> </cics_mtom_handler> <transport> </transport> <service> . </service>
91

New Containers for MTOM/XOP processing DFHWS-CID-DOMAIN
Contains the domain name that is used to generate content-ID values for referencing binary attachments
DFHWS-MTOM-IN
Holds information about the MTOM options for the pipeline Holds information about the message format received
DFHWS-MTOM-OUT
Holds information about the MTOM options for the pipeline Holds information about what XOP processing should take place
DFHWS-XOP-IN
Holds information about the binary attachments and their containers
DFHWS-XOP-OUT
Holds information about the containers and their binary attachments
Notes
DFHWS-CID-DOMAIN is a container of DATATYPE(CHAR). It contains the domain name that is used to generate content-ID values for referencing binary attachments. DFHWS-MTOM-IN is a container of DATATYPE(BIT) that holds information about the specified options for the <cics_mtom_handler> element of the pipeline configuration file, and information about the message format that has been received in the pipeline. DFHWS-MTOM-OUT is a container of DATATYPE(BIT) that holds information about the specified options for the <cics_mtom_handler> element of the pipeline configuration file. DFHWS-XOP-IN is a container of DATATYPE(BIT). It contains a list of references to the binary attachments that have been unpackaged from an inbound MIME message and placed in containers using XOP processing. Each attachment record in the DFHWS-XOP-IN container is comprised of: - The name of the container that holds the MIME headers. - The name of the container that holds the binary attachment. - The content-ID, stored as a varying-length character string in ASCII format. DFHWS-XOP-OUT is a container of DATATYPE(BIT). It contains a list of references to the containers that hold binary attachments. The binary attachments are packaged into an outbound MTOM message by the MTOM handler program. Each attachment record in the DFHWS-XOP-OUT container is comprised of: - The name of the container that holds the MIME headers for the binary attachment. - The name of the container that holds the binary attachment. - The content-ID, stored as a varying-length character string in ASCII format.
Web Services and Security

Business Process Execution Language
Business Processes
WS-Coordination WS-Security WS-Transactions WSDL WS-Policy
WS-Reliable Messaging
Quality of Service
UDDI
Description and Discovery
SOAP, SOAP Attachments XML Transports
Other protocols Messaging and Encoding Other services WS-Secure
Conversation WS-Security Policy

Transport
WS-Federation WS-Authorization WS-Trust WS-Privacy
WS-Security (framework)
Kerberos profile Mobile profile
94
X509 profile Username profile
XrML profile SAML profile

CICS Transaction Server 3.1

WS-Security (OASIS Standards) WSS: SOAP Message Security V1.0
XML Encryption syntax and processing XML-Signature syntax and processing
WSS: Username Token Profile V1.0 WSS: X.509 Token Profile V1.0 WS-I basic Security Profile 1.0 Provides guidance on the WS-Security specifications Based on Working Group Draft dated 14th June 2005 WS-Security protects the privacy and integrity of SOAP messages
95
Notes
CICS Transaction Server for z/OS provides support for a number of related specifications that enable you to secure SOAP messages. The Web Services Security (WSS): SOAP Message Security 1.0 specification describes the use of security tokens and digital signatures to protect and authenticate SOAP messages. Web Services Security protects the privacy and integrity of SOAP messages by, respectively, protecting messages from unauthorized disclosure and preventing unauthorized and undetected modification. WSS provides this protection by digitally signing and encrypting XML elements in the message. The elements that can be protected are the body, or any elements within the body or the header. Different levels of protection can be given to different elements within the SOAP message.
96

WS-Security support
CICS supplies a DFHWSSE1 message handler Outbound Messages
Encryption and digital signing of entire SOAP body
Inbound Messages
Decryption of any encrypted elements present in SOAP messages
SOAP body, header or elements
97
Notes
CICS Transaction Server for z/OS provides support for WSS: SOAP Message Security through the use of a CICS-supplied message handler, DFHWSSE1. For outbound messages, CICS provides support for digital signing and encryption of the entire SOAP body. For inbound messages, CICS supports messages in which the body, or elements of the body and header are encrypted or digitally signed. CICS does not support Web Services Security for atomic transactions (WS-AT). There is a significant performance impact when you use WSS to secure your Web services. The main advantage of implementing WSS is that by encrypting part of a SOAP message, you can send the message through a chain of intermediate nodes, all of which might have legitimate reasons to look at the SOAP header to make routing or processing decisions, but are not allowed to view the content of the message. By encrypting those sections that need to be confidential you: - do not incur the overhead of encrypting and decrypting at every node in a chain of intermediate processes - can route a confidential message over a public network of untrusted nodes, where only the ultimate recipient of the data can understand it.
98

WS-Security authentication support
How a user identity will be inferred from an inbound request How CICS will propagate an identity on an outbound request Options include:
Username token X509 token Asserted identity
99
Notes
Web Services Security (WSS): SOAP Message Security is a set of enhancements to SOAP messaging that provides message integrity and confidentiality. WSS: SOAP Message Security is extensible, and can accommodate a variety of security models and encryption technologies. WSS: SOAP Message Security provides three main mechanisms that can be used independently or together. They are: The ability to send security tokens as part of a message, and for associating the security tokens with message content The ability to protect the contents of a message from unauthorized and undetected modification (message integrity) The ability to protect the contents of a message from unauthorized disclosure (message confidentiality). WSS: SOAP Message Security can be used in conjunction with other Web service extensions and application-specific protocols to satisfy a variety of security requirements. The specification is published by the Organization for the Advancement of Structured Information Standards (OASIS) at Web Services Security: SOAP Message Security 1.0 (WS-Security 2004).
100
WS-Trust
WS-Trust 1.3
Submitted to OASIS standardization process
Derived from W3C specification dated 25 February 2005 Recommended March 2007
Provides a framework for building trust relationships

Sender and Receiver in different security domains Security tokens must be vouched for by trusted third party Trusted third party, called Security Token Service (STS)
WS-Trust defines standard protocols and standard WSDL interfaces to communicate with an STS
101
Notes
The Web Services Trust Language specification enhances Web Services Security further by providing a framework for requesting and issuing security tokens, and managing trust relationships between Web service requesters and providers. This extension to the authentication of SOAP messages enables Web services to validate and exchange security tokens of different types using a trusted third party. This third party is called a Security Token Service (STS).
102
CICS Support of WS-Trust

Interoperate with a Security Token Server CICS supplied security handler
Inbound messages
Validate the security token in the WS-Security header Exchange the security token in the WS-Security header
Outbound messages
Exchange the security token to be used in the WS-Security header
Trust Client Interface User supplied custom message handler

No requirement for the CICS provided security handler
Directly interact with an STS

Issue or validate security tokens from the message header
Channel and container interface

Notes
CICS support for securing Web services has been enhanced to include an implementation of the Web Services Trust Language (or WS-Trust) specification. CICS can now interoperate with a Security Token Service (STS), such as Tivoli Federated Identity Manager, to validate and issue security tokens in Web services. This enables CICS to send and receive messages that contain a wide variety of security tokens, such as SAML assertions and Kerberos tokens, to interoperate securely with other Web services. You can configure the CICS-supplied security handler to define how CICS should interact with an STS. The <wsse_handler> element in the pipeline configuration file now includes additional elements and attributes to configure this support. CICS can either validate or exchange the first security token or the first security token of a specific type in the message header. If you want more sophisticated processing to take place, CICS provides a separate Trust client interface that you can use in a custom message handler. You can use the Trust client instead of the security handler or in addition to it.
104

<authentication> element
Specifies the use of security tokens in the headers SOAP messages
trust attribute
none, basic, blind, signtaure
mode attribute
None, basic, signature
Trust and mode attributes specify

Whether asserted identity is used Combination of security tokens that are used in SOAP messages
105
Notes
Taken together, the trust and mode attributes specify: - whether asserted identity is used - the combination of security tokens that are used in SOAP messages. Asserted identity allows a trusted user to assert that work should run under an different identity, the asserted identity, without the trusted user having the credentials associated with that identity. When asserted identity is used, messages contain a trust token and an identity token. The trust token is used to check that the sender has the correct permissions to assert identities, and the identity token holds the asserted identity, that is, the user ID under which the request is executed. Use of asserted identity requires that a service provider trusts the requester to make this assertion. In CICS, the trust relationship is established with security manager surrogate definitions: the requesting identity must have the correct authority to start work on behalf of the asserted identity.
106

Service requestor (outbound) attributes
trust=none
mode=none
No credentials are added to the message
mode=basic
Invalid combination of attributes
mode=signature
X509 security token added to the message > Identified by the <certificate label> > Algorithm specified by <algorithm> element
107
Notes
trust none mode none basic signature Meaning No credentials are added to the message Invalid combination of attribute values Asserted identity is not used. CICS uses a single X.509 security token which is added to the message, and used to sign the message body. The certificate is identified with the <certificate_label> element, and the algorithm is specified in the <algorithm> element
108

trust=basic
mode=none
mode=basic
mode=signature
109
Notes
trust basic mode (any) Meaning Invalid combination of attribute values
110

trust=blind
mode=none
mode=basic
Asserted identify is not used > CICS adds an identity token to the message > Identity taken from DFHWS-USER (currently running task) > CICS does not add a trust token
mode=signature
111
Notes
trust blind mode none basic Meaning Invalid combination of attribute values Asserted identity is not used. CICS adds an identity token to the message, but does not provide a trust token. The identity token is a username with no password. The user ID placed in the identity token is the contents of the DFHWS-USERID container (which, by default, contains the running tasks user ID). Invalid combination of attribute values
signature
112

trust=signature
mode=none
mode=basic
Asserted identify is used > CICS adds an identity token to the message > Identity taken from DFHWS-USER (currently running task) > CICS adds a trust token > X509 certificate take from <certificate label>
mode=signature
113
Notes
trust signature mode none basic Meaning Invalid combination of attribute values Asserted identity is used. CICS adds the following tokens to the message: The trust token is an X.509 security token. The identity token is a username with no password. The certificate used to sign the identity token and message body is specified by the <certificate_label>. The user ID placed in the identity token is the contents of the DFHWS-USERID container (which, by default, contains the running tasks user ID). Invalid combination of attribute values
signature
114

Service provider (inbound) attributes
trust=none
mode=none
No credentials will be extracted from the message
mode=basic
Message must contain a username security token with password > Username placed in DFHWS-USERID
mode=signature
Message must contain a X509 certificate used to sign the message body
115
Notes
trust none mode none Meaning Inbound messages need not contain any credentials, and CICS does not attempt to extract or verify any credentials that are found in a message. However, CICS will check that any signed elements have been correctly signed. Inbound messages must contain a username security token with a password. CICS puts the username in the DFHWS-USERID container. Inbound messages must contain an X.509 security token that has been used to sign the message body.
basic
signature
116

trust=basic
mode=none
mode=basic
Inbound message must use asserted identity > Trust token is a username token with password > Identity token is a username token without password > Username (identity) is placed in DFHWS-USERID
mode=signature
Inbound message must use asserted identity Trust token is a username token with password Identity token is a X509 certificate Username associated with the certificate is placed in DFHWS-USERID
117
Notes
trust basic mode none basic Meaning Invalid combination of attribute values Inbound messages must use asserted identity: The trust token is a username token with a password. The identity token is a second username token without a password. CICS puts this username in container DFHWS-USERID. Inbound messages must use asserted identity: The trust token is a username token with a password. The identity token is an X.509 certificate. CICS puts the user ID associated with the certificate in container DFHWS-USERID.
signature
118

trust=blind
mode=none
mode=basic
Inbound message must contain an identity token > Must contain a username > Optionally may contain a password > CICS will verify a username/password combination > Username is placed in DFHWS-USERID
mode=signature
Inbound message contain an identity token Identity is the first X509 certificate in the message Username associated with the certificate is placed in DFHWS-USERID
119
Notes
trust blind mode none basic Meaning Invalid combination of attribute values Inbound messages must contain an identity token, where the identity token contains a user ID and optionally a password. CICS puts the user ID in the DFHWS-USERID container. If no password is included, CICS uses the user ID without verifying it. If a password is included, the security handler DFHWSSE1 verifies it. Inbound messages must contain an identity token, where the identity token is the first X.509 certificate in the SOAP message header. The certificate does not need to have signed the message. The security handler extracts the matching user ID and places it in the DFHWS-USERID container.
signature
120

trust=signature
mode=none
mode=basic
Inbound message must use asserted identity > Trust token is an X509 certificate > Identity token is a username token without a password > Username is placed in DFHWS-USERID
mode=signature
Inbound message must use asserted identify Trust token is an X509 certificate Identity token is a second X509 certificate Username associated with the certificate is placed in DFHWS-USERID
121
Notes
trust Signature mode none basic Meaning Invalid combination of attribute values Inbound messages must use asserted identity: The trust token is an X.509 certificate. The identity token is a username token without a password. CICS puts the username in container DFHWS-USERID. The identity token and the body must be signed with the X.509 certificate. Inbound messages must use asserted identity: The trust token is an X.509 certificate. The identity token is a second X.509 certificate. CICS puts the user ID associated with this certificate in container DFHWS-USERID. The identity token and the body must be signed with the first X.509 certificate (the trust token).
signature
122

<sts_authentication> element
Specifies that a Security Token Service (STS) should be used
For authentication In a provider pipeline determines what type of request is sent
Issue an identity token Validate the provided identity token
Not required in a provider pipeline
<sts_endpoint> element
Specifies the location of the Security Token Service
<auth_token_type> element
Specifies what type of identity token is required from the STS
Notes
<sts_authentication> element Specifies what type of request CICS should send to the STS when a message is received in the service provider pipeline. Valid values are: issue validate The STS issues an identity token for the SOAP message. The STS validates the provided identity token and returns whether the token is valid to the security handler.I f you do not specify this attribute, CICS assumes that the action is to request an identity token. In a service requester pipeline, you do not need to specify this attribute because CICS always requests that the STS issues a token.
<sts_endpoint> element This element contains a URI that points to the location of the Security Token Service (STS) on the network. It is recommended that you use SSL or TLS to keep the connection to the STS secure, rather than using HTTP. You can also specify a WebSphere MQ endpoint using the JMS format of URI. <auth_token_type> element Specifies what type of identity token is required from the Security Token Service (STS).
124

Trust Client Interface User supplied custom message handler
Can be used with or replace the CICS provided security handler
Directly interact with an STS

Extract the security token from the inbound/outbound message Request the STS to validate/issue using the security token Process the STS response
Provider mode > Update DFHWS-USERID container Requestor mode > Add the returned token to the message security header
125
Notes
Invoking the Trust client from a message handler CICS provides an interface so that you can write your own message handler to invoke a Security Token Service. This enables you to perform more advanced processing than the CICS-supplied security handler. You can use the Trust client instead of the security handler, or in addition to it. If you want to use the Trust client interface: 1. Extract the correct token from the security message header of the inbound or outbound message. 2. Link to program DFHPIRT passing the channel DFHWSTC-V1 and the appropriate containers. 3. DFHPIRT returns with the response from the STS. A successful response is stored in the DFHWS-RESTOKEN container. If the STS encounters an error, this is put in the DFHWS-STSFAULT container. 4. Process the response as appropriate. In provider mode, your pipeline processing must ensure that a user name and password that CICS can understand is placed in the DFHWS-USERID container In requester mode, your message handler should add the correct token to the outbound message security header.
126

Trust Client Interface DFHPIRT requires a channel named DFHWSTC_V1
Input containers
DFHWS-STSURI DFHWS-STSACTION DFHWS-IDTOKEN DFHWS-TOKENTYPE DFWS-SERVICEURI
Output containers
DFHWS-RESTOKEN DFHWS-STSFAULT
127
Notes
Invoking the Trust client from a message handler Link to program DFHPIRT passing the channel DFHWSTC-V1 and the following containers: - DFHWS-STSURI, the location of the STS on the network | - DFHWS-STSACTION, the type of request that the STS should perform The two supported actions are issue and validate. - DFHWS-IDTOKEN, the token that should either be verified or exchanged by the STS - DFHWS-TOKENTYPE, the type of token that the STS should send back in the response - DFHWS-SERVICEURI, the URI of the Web service operation that is being invoked Response from the STS DFHWS-RESTOKEN, response from the STS if successful DFHWS-STSFAULT, error response if unsuccessful
128

New options in CICS TS V3.2
MAPPING-LEVEL={1.0, 1.1, 1.2, 2.0}
Level of mapping that the CWSA should use when generating the Web service binding file and Web service description or language structure
MINIMUM-RUNTIME-LEVEL={MINIMUM, 1.0, 1.1, 1.2, 2.0, CURRENT}

Minimum CICS runtime environment that the Web service binding file can be deployed into
CCSID
Specifies the CCSID to be used at runtime
TRANSACTION
In a service provider, specifies the name of an alias TRANID
USERID
In a service provider, specifies a user ID which can be used by any client
Notes
There are new parameter options on the CICS Web Service Assistants: MAPPING-LEVEL={1.0|1.1|1.2|2.0} Specifies the level of mapping that the CWSA should use when generating the Web service binding file and Web service description or language structure. MINIMUM-RUNTIME-LEVEL={MINIMUM|1.0|1.1|1.2|2.0|CURRENT} Specifies the minimum CICS runtime environment that the Web service binding file can be deployed into. If you select a level that does not match the other parameters that you have specified, you receive an error message. CCSID=value 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). You can use this parameter with any mapping level but this will require a minimum run time level of 1.2 TRANSACTION=name 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. USERID=id 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.

Mapping Level
1.0 CICS TS 3.1 base level 1.1 Variable length binary data mapped to container XML schema list and union types mapped to character arrays Other character and binary data mappings to containers depending on data length 1.2 Character and binary data of more than 32,767 bytes mapped to a container Support for:
Multiple variable length mappings COMP-1 (float) COMP-2 (double) LEVEL 88 toleration Base64binary data mapped to a field in the language structure Improved messages in the event of conversion errors
2.0 CICS TS 3.2 base level
2.1
Support for:
type:any, type:anyType XML-ONLY for applications that want to do their own XML parsing
131
Notes
There are new mapping levels for the CICS Web Service Assistants. 1.0 The Web service binding file and language structure is generated using CICS TS 3.1 mapping levels. 1.1 XML attributes, <list>, and <union> data types are mapped to the language structure. Character and binary data that has a maximum length of more than 32,767 bytes is mapped to a container. The container name is created in the language structure. 1.2 Use the parameters CHAR-VARYING and CHAR-VARYING-LIMIT to control how character data is mapped and processed at run time. If you do not specify either of these parameters, binary and character data that has a maximum length less than 32768 bytes is mapped to a VARYING structure for all languages except C++, where character data is mapped to a null terminated string. 2.0 Use this mapping level to take full advantage of the enhancements to the mapping between the language structure and Web services binding file.
132

DFHLS2WS new options

WSDL_1.1(<HFS filename location>) WSDL_2.0(<HFS filename location>) SOAPVER(1.1|1.2|ALL) URI parameter may now specify an relative or absolute URI
DFHWS2LS new options

Automatically determines the WSDL version OPERATION=value
Specifies the subset of valid operations that are required for a requestor Used to limit the size of the WSBIND file
WSDL-SERVICE=value
Specifies the wsdl:Service element to be used when there is more than one Service element for a Binding element
133
Notes
WSDL_1.1(<HFS filename location>) The WSDL_1.1 and WSDL parameters are synonymous, though only one of them may be used. Both the WSDL_1.1 and WSDL_2.0 parameters may be used if both versions of WSDL are desired, though only one of them is required. WSDL_2.0(<HFS filename location>) This parameter is used to tell DFHLS2WS where to write the WSDL 2.0 version of the WSDL file. It may be used in conjunction with one of the WSDL and WSDL_1.1 parameters if both versions of WSDL are desired, though only one of them is required. The use of this parameter forces the minimum runtime level to 2.0 regardless of the mapping level specified (in much the same way as CCSID forces it to 1.2). SOAPVER(1.1 | 1.2 | ALL) This optional parameter is used to tell DFHLS2WS which SOAP level to use in the generated WSDL (and also which SOAP level to check at install time). Its default value depends on which WSDL versions have been specified. If WSDL 1.1 is required (and not 2.0) then it defaults to SOAP 1.1. If WSDL 2.0 is required (and not 1.1) then it defaults to SOAP 1.2. If both WSDL 1.1 and 2.0 are required then it defaults to generating Bindings suitable for both SOAP 1.1 and SOAP 1.2 into both the WSDL 1.1 and the WSDL 2.0 documents. If either the '1.2' option or the 'ALL' option is used then the generated WSBind file must be installed into a SOAP 1.2 PIPELINE. If the '1.1' option is selected then the WSBind file should be installed into a SOAP 1.1 PIPELINE but can be tolerated in a SOAP 1.2 PIPELINE. URI This parameter will be changed for all runtime levels such that it may specify either a relative URI (as is currently the case) or an absolute URI. If a relative URI is specified then this value is processed as at TS 3.1. If an absolute URI is specified then the following occurs: DFHWS2LS - the host and port information (or WMQ equivalent information) is ignored, but the rest of the URI (the relative part) is processed as in TS 3.1. DFHLS2WS - as above. It is also used as the whole of the soap:address element in the generated WSDL, thereby saving the user from having to change the generated WSDL by hand to supply an HTTP host and port (or WMQ equivalent information).
134
Notes
DFHWS2LS now automatically determines the WSDL version of Web service description that has been supplied as input. The batch job has been enhanced to provide you with more flexibility in how to handle the Web service description. wsdl:Bindings elements can be associated with multiple wsdl:Service elements in Web service descriptions. A new parameter has been added to enable you to select a specific Service element within the Web service description. When you are creating a service requester application, you can now specify a subset of wsdl:Operation elements that you want to implement and create a Web service binding file based on that subset. This can be useful when you have a very large WSDL file. By only using a subset of Operation elements, you can save on storage by generating a smaller Web service binding file. The following new parameters have been added to DFHWS2LS: OPERATION=value For Web service requester applications, specifies a subset of valid wsdl:Operation elements from the Web service description that should be used to generate the Web service binding file. Each Operation element should be separated by a space; the list can span more than one line if necessary. This parameter can be used for both WSDL 1.1 and WSDL 2.0 documents. WSDL-SERVICE=value Specifies the wsdl:Service element that should be used when the Web service description contains more than one Service element for a Binding element. If you specify a value for the BINDING parameter, then the Service element that you specify for this parameter must be consistent with the specified Binding element. You can use this parameter with either WSDL 1.1 or WSDL 2.0 documents.
Web Services Statistics

Pipeline statistics Web Service statistics
Name Configuration file Shelf directory WSBIND directory Use count
Name Program interface Message validation PIPELINE name URIMAP name WSBIND file WSDL file Porttype Endpoint Program name Use count
136
Migration of the CICS TS Version 2 SOAP Feature

Coexistence supported for migration
Version 2 feature may be installed on CICS TS 3 Provides the same level of function as on Version 2
Migration to CICS TS 3 Web Services requires
Modifying your message adapters to use the new interfaces Review your use of containers. The SOAP for CICS feature uses BTS containers; the Web services support in CICS TS V3;1 does not use BTS. The containers names used in the Web services support, are different from the names used in the SOAP feature Replacing the user-written handlers with SOAP header handlers defined in the PIPELINE configuration file
137
Models for SOA Integration of CICS Applications

Service end-point in CICS Utilizing Web Services support in CICS SOAP over HTTP or SOAP over MQ/JMS Service end-point in intermediary system Multiple choices for intermediary system
WebSphere Application Server WebSphere Message Broker WebSphere Process Server
Utilizing strategic connectors between front-end and CICS
138
The Two CICS Models of SOA Integration

Other/Any CICS TS (Service Provider) Business Function Web Service Client CICS Web Services support
Integration logic I
Business logic B
Data access D
Other/Any
Intermediary
CICS TS CICS Program
Web Service Client
Web services end-point
connector
Business logic B
139
Strategic Connectors
Standard architectures provide comprehensive development tools and runtime support in CICS
1 Web services over SOAP (Simple Object Access Protocol) 2 J2C (J2EE Connector Architecture) 3 Enterprise JavaBeans (J2EE EJB)
Standard transports are suitable for use by applications that require greater control of the protocol and do not need the development tools or qualities of service provided by the standard architectures. These applications will assume more responsibility for systems management, security, and recovery
4 HTTP (HyperText Transfer Protocol) 5 WebSphere MQ (MQ APIs or JMS - Java Messaging Service) 6 TCP/IP sockets
Access to CICS Strategic Connectors

CICS TS
Web services Intermediary Server Web services J2C

Web Service Implementation RMI
2
I B D
HTTP WMQ Sockets
4 5 6
141
Access from CICS Strategic Connectors

CICS TS
1 Intermediary Server
Web service
B
Web services
3 4 5 6
EJB HTTP WMQ Sockets Service requester
142
Factors Influencing your Integration Choices

Business factors Agreed company standard or reference frameworks Preferred application development environment and tools Availability of skills Technical factors Security Transactional scope Performance Reliability, availability and scalability (RAS) Application interface consumability Synchronous or asynchronous invocation Inbound and outbound capability Client/server coupling Data conversion State management Applications today are typically delivered across several e-business clients
Notes
The SOAP for CICS feature, orderable with CICS TS V2.2 and V2.3, is not orderable with CICS TS V3. However, to assist migration for customers who already have this feature, the feature may be used and is supported with CICS TS V3, and applications will continue to run. Customers are recommended to migrate to the Web services support capabilities of CICS TS V3. The SOAP for CICS feature relies to a considerable extent upon user-written code, and therefore it is not possible to set out a step-by-step migration task. However, here are some of the things you will need to think about . Consider using the Web services assistant to construct and parse SOAP messages. If you use SOAP messages, but decide not to use the Web services assistant, you may be able to reuse your existing code for constructing and parsing the messages. However, you should consider whether to use the CICS-provided SOAP message handlers, because they are designed to work with SOAP 1.1 and SOAP 1.2 messages. Review your use of containers. The SOAP for CICS feature uses BTS containers, whereas CICS Transaction Server uses channel containers. Consider how to migrate the function that was provided by your pipeline programs. The pipeline in the SOAP for CICS feature has a fixed number of user-written programs, each with a designated purpose. The function provided by some of these programs is provided in CICS Transaction Server by the CICS-provided SOAP message handlers, so you may be able to dispense with these programs altogether. The way that pipeline programs communicate with CICS, and with one another, has changed, so you will need to review these programs to see if they can be reused in the new environment. In the SOAP for CICS feature, you could have just one pipeline for all your service provider applications, and one for all your service requesters. In CICS Transaction Server, you can configure many different pipelines.
144
Additional Documentation
CICS TS info on the web
Home page
http://www.ibm.com/cics/
Library pages
http://www-306.ibm.com/software/htp/cics/tserver/v31/library/ http://www-306.ibm.com/software/htp/cics/tserver/v32/library/
Web Services Guide

A new book in the CICS Infocenter for CICS TS V3.1
145
SG24-7206-00
SG24-7126-00
SG24-7144-00
SG24-5466-05
SG24-5456-01
Summary
CICS Support of Web Services
Allows for re-use of existing business assets

No change to application code
Allows for development of new CICS applications using web services

CICS infrastructure support
CICS utilities
WSDL to language structure generation (batch tool) Language structure to WSDL generation (batch tool) Runtime support for XML to COMMAREA and vice versa mapping
Resource definitions on-line

URIMAP PIPELINE WEBSERVICE
EXEC support for outbound calls

Monitoring, statistics and problem determination support
151

CICS Support of Web Services allows for the reuse of existing business assets in a Web Services environment. Existing COMMAREA application programs can function as a service provider without change. The CICS Web Services support allows the development of new CICS applications that function as a service requester invoking an existing web service. CICS provides utilities that will generate a language structure (copybook) from existing Web Service Definition Language (WSDL) or can generate WSDL from an existing language copybook. The utility also generates information about the XML to COMMAREA transformation that allows CICS to provide the message adapter function. In this role, CICS will be able to map the XML structure into an existing COMMAREA and after the service provider application has finished, map the COMMAREA back to an XML structure for subsequent transmission to the requester. CICS has the capability of not only using a COMMAREA to pass information to the service program but can also use the new CHANNEL/CONTAINER constructs, eliminating the 32k restriction that a COMMAREA imposes. CICS provides RDO support for the definition of the URI mapping to a web service, definition and configuration of the pipeline process and definition of the actual web service. CICS provides the standard qualities of services for web support including monitoring, statistics and problem determination support.
Notes
The improvements to the Web services support in CICS include compliance with the latest versions of specifications and standards to enable interoperability with other Web service providers and requesters. There is additional functionality in the runtime support to implement the supported specifications and standards. CICS now supports creating and deploying Web services using Web service description documents that comply with the WSDL 2.0 specification. There are improvements to the Web services assistant to help you more easily create and deploy Web services in CICS. In standard SOAP messages, binary objects are base64 encoded and included in the message body. This significantly increases their size, and for very large binary objects, this can impact transmission time. CICS has implemented support for MTOM/XOP to provide a solution to this problem.
153

Manual Web Services and CICS

Hochgeladen von

Dokumentinformationen

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Manual Web Services and CICS

Hochgeladen von

Copyright:

Verfügbare Formate

Advanced Technical Support

Web Services and CICS Applications

2006 IBM Corporation

Advanced Technical Support

Web Services - Notes

2006 IBM Corporation

Advanced Technical Support

2006 IBM Corporation

Advanced Technical Support

Web Services - Notes

2006 IBM Corporation

Advanced Technical Support

CICS Web Services Assistants

Advanced Technical Support

Web Services - Notes

2006 IBM Corporation

Advanced Technical Support

Reasons to use Web Services in CICS

2006 IBM Corporation

Advanced Technical Support

Web Services - Notes

2006 IBM Corporation

Advanced Technical Support

Web Services Introduction

A Web Service is an interface that:

A Web Service is described:

Advanced Technical Support

Web Services - Notes

2006 IBM Corporation

Advanced Technical Support

The Web Services Stack

WS-Security family of specifications

WSDL SOAP XML

Description and Discovery Messaging and Encoding

2006 IBM Corporation

Advanced Technical Support

The Web Services Base Technologies

WS-Security family of specifications

WSDL SOAP XML

Description and Discovery Messaging and Encoding

2006 IBM Corporation

Advanced Technical Support

CICS and Web services standards

CICS TS V3.2 adds support for these Web services standards

* WebSphere MQ can also be used as the transport layer

2006 IBM Corporation

Advanced Technical Support

Web Services - Notes

2006 IBM Corporation

Advanced Technical Support

Advanced Technical Support

Advanced Technical Support

2006 IBM Corporation

Advanced Technical Support

2006 IBM Corporation

Advanced Technical Support

Advanced Technical Support

Web Services Introduction

Service Registry Publish

2006 IBM Corporation

Advanced Technical Support

Web Services - Notes

2006 IBM Corporation

Advanced Technical Support