manual web services and cics

Advanced Technical Support

© 2006 IBM Corporation

Web Services and CICS Applications


© 2006 IBM Corporation2

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




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 faste r response times and reduced costs

� Improve system management to enable management of more with less

� Simplify the development process to reduce applicat ion 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 maintenanceconsuming 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 moreefficient 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 anddisconnected 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• 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 accessiblethrough 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.



The Web Services “Stack”

WS-Policy

WS-Security family of

specifications

UDDI

Qualityof Service

Messagingand Encoding

Transport

BusinessProcesses

Other protocolsOther services

Business Process Execution Language (BPEL)

Descriptionand DiscoveryWSDL

SOAP

XML

Transports

WS-Coordination

WS-Transactions

WS-Reliable Messaging

WS-DistributedManagement



The Web Services Base Technologies

WS-Policy

WS-Security family of

specifications

UDDI

Qualityof Service


Transport

BusinessProcesses


Business Process Execution Language (BPEL)

Descriptionand DiscoveryWSDL

SOAP

XML

Transports

WS-Coordination

WS-Transactions

WS-Reliable Messaging

WS-DistributedManagement



CICS and Web services standards

� CICS TS V3.1 supports the following Web services st andards– 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 st andards– 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




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-AtomicTransactionspecification. 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: http://www.w3.org/TR/wsdlSOAP 1.1 specification: http://www.w3.org/TR/2000/NOTE-SOAP-20000508/SOAP 1.2 specification: http://www.w3.org/TR/soap12-part0/XML 1.0 specification: http://www.w3.org/TR/2004/REC-xml-20040204/



NotesExtensible 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/



NotesWS-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.1is 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 (M TOM) 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/.



NotesWeb 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/ws-sx/ws-trust/200512/ws-trust-1.3-spec-cd-01.pdf



NotesWeb 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 WS-AtomicTransaction 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 WS-AtomicTransaction 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 protocolsthat 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/.



Web Services Introduction…

� Architecture– Service provider

• “Owns” the service• Creates the WSDL• Publishes the WSDL• Processes requests

– Service requester• “Finds” the service• Binds to the service

– Invokes the service using the WSDL

– Service Registry• Hosts the service description• Optional for statically bound requesters

ServiceRequester

ServiceProviderBind

FindWSDL, UDDI

PublishWSDL, UDDI

ServiceRegistry

SOAP



Web Services - NotesThe 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.



Web Services Introduction…� 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

type

binding

serviceport

Input

Output

portType

message

definition

operation

abstractserviceinterfacedefinition

how the service isimplemented

location ofservice




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 provider’s 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




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.



Production and usage of WSDL

ServiceRequester

ServiceProvider

Input message

Output message

WSDL

� location� protocol� operation� message format

IDE tools IDE tools

� Requests from Service Requesters will be generated based on the information contained in WSDL

� IDE tools help generation of WSDL or application




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



Web Services Enablement

Generate

ExistingBusiness App

(e.g. COBOL, C, C++, PLI)

New service: WSDL

Bottom-up

Generate

Existing service description WSDL

NewBusiness App (COBOL,

C, C++, PLI)

Top-down

Map andGenerate

Meet in the middle

ExistingBusiness App

(COBOL, C, C++, PLI)

Existing service description WSDL




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.



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




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.



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



Meet in the middle approach in CICS TS V3

� Pure ‘top down’ or ‘bottom up’ will not be suitable i n all situations

– In such situations, a wrapper program may provide a solution

� If the language structure uses data types not suppo rted 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 s tructure 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 a n existing program

– The WSDL and the program may not match exactly.

– A wrapper program could perform some intermediate mappings

PipelineConversion

(SOAP ↔↔↔↔COMMAREA)

BusinessLogic

WrapperProgram




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.



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




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.




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




�WMQ definition

–Required when CICS is a service provider

–Pick the target up from the RFH2 header if present, otherwise default to trigger data

DEFINE

QLOCAL(‘queuename’)

DESCR(‘description’)

PROCESS(‘processname’)

INITQ(‘initqueue’)

TRIGGER

TRIGTYPE(FIRST)

TRIGDATA(‘path part of URI’)

BOTHRESH(nnn)

BOQNAME(‘requeuename’)



Web Services - NotesA 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 queueDEFINEQLOCAL ('queuename')DESCR ('description')PROCESS(processname)INITQ('initqueue')TRIGGERTRIGTYPE(FIRST)TRIGDATA('default target service')BOTHRESH(nnn)BOQNAME('requeuename')

queuename is the local queue nameprocessname 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 objectinitqueue 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.



CICS Resource Definitions…� 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 Enabled | Disabled USAge ==> Server Server | Client | Pipeline

UNIVERSAL RESOURCE IDENTIFIER SCheme ==> HTTP HTTP | HTTPS HOST ==> (Mixed Case) ==> PAth ==> (Mixed Case) ==>

==> ==> ==>

ASSOCIATED CICS RESOURCES TCpipservice ==> Analyzer ==> No No | Yes COnverter ==> TRansaction ==> PRogram ==> PIpeline ==> Webservice ==> (Mixed Case)



Web Services - NotesThe 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.



CICS Resource Definitions…� PIPELINE definition

– Defines the processing nodes for a web service request• Different pipelines for:

– Requester and provider

– 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

PIPELINE ==> Group ==> Description ==> Status ==> Enabled Enabled | Disabled Configfile ==> (Mixed Case) ==>

==> ==> ==>

Shelf ==> (Mixed Case) ==>

==> ==> ==>

Wsdir ==> (Mixed Case) ==>

==> ==> ==>



Web Services - NotesA 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.




� 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




The Pipeline configuration file, named in a PIPELINE resource definition, is used to describethe 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 providerhandling 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.




� Pipeline XML configuration for a service provider

<?xml version="1.0" encoding="UTF- 8"?>

<provider_pipeline xmlns="http://www.ibm.com/software/htp/cics/pipelin e"

.....xmlns:xsi="http://www.w3.org/2001/XMLSchema- instance"

.....xsi:schemaLocation=“http://www.ibm.com/softwar e/htp/cics/pipeline 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.



CICS Resource Definitions…� WEBSERVICE definition

– Defines the application specific details for a web service request• Defines the execution environment

for Web Service application– 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

– VALIDATION• Run time SOAP message

validation against WSDL schema

WEBSERVICE ==> Group ==> Description ==> Pipeline ==> (Mixed Case) ==>

==> ==> ==>

WSBIND ==> (Mixed Case) ==>

==> ==> ==>

WSDLFILE ==> (Mixed Case) ==>

==> ==>

VALIDATION ==> NO NO|YES



Web Services - NotesA 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

HFS

WSDL

WSBind

CICS providedutility

WEBSERVICE

pipelineconfig

URIMAP

CICS TS V3TCPIPSERVICE

CPIHCWXNServiceRequester

URIMAPmatching

CSOL

Pipeline

handlers

handlers

handlers

SOAP message

data mapping

BusinessLogic

Languagestructure

dynamicinstall

dynamicinstall

PIPELINE



CICS as a service requester

CICS TS V3User Transaction

data mapping

BusinessLogic

Pipeline

handlers

handlers

handlersPIPELINE

WEBSERVICE

dynamicinstall

HFS

WSBind

WSDL

pipelineconfig

CICS providedutility

ServiceProvider

SOAP message

Languagestructure



� CICS as a service provider

� CICS as a service requester

CICS usage of the WSBind file

businesslogic

pipelineService

Requester

CICS

Data mapping

WSDL

CICS Web services

HLL data structureSOAP body

WSBindfile

WEBSERVICEresource

businesslogic

pipeline ServiceProvider

CICS

Data mapping

WSDL

CICS Web services

SOAP bodyHLL data structure

WEBSERVICEresource

WSBindfile




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.



Application Programming Interfaces

� Invoking a Web Service from a CICS application program

– CICS as a service requesterEXEC 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.



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



Web Services - NotesHere is the syntax diagram for SOAPFAULT CREATE. Full details of all the commands can be found in the CICS Infocenter.



Support for WSDL 2.0

� WSDL 2.0 is a “Candidate Recommendation” with the W3 C

– 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



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.



Support for WSDL 2.0…

� 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



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.




� 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



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.




� 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 as the provider– CICS will receive a message and respond with a normal response or fault

• CICS as the requester– CICS application will send a message and expect a normal response of fault



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




� Message exchange patterns supported…

– Robust in-only• CICS as the provider

– CICS will receive a message and respond only if an error occurs

• CICS as the requester– 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 as the provider

– CICS will receive a message and may respond with> A normal response> An error response> Nothing (no response)

• CICS as the requester– CICS application will send a message and expect:

> A normal response> An error response> Nothing (no response)



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 therequester 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 definit ion



NotesRobust-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 thisMEP.

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 anormal 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)



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



NotesThere 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



NotesDFHWS-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 MEP URI

1 In-Only http://www.w3.org/2006/01/wsdl/in-only 2 In-Out http://www.w3.org/2006/01/wsdl/in-out 4 Robust-In-Only http://www.w3.org/2006/01/wsdl/robust-in-only 8 In-Optional-Out http://www.w3.org/2006/01/wsdl/in-opt-out



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



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.



Improved Support for Binary Attachments…� 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 m ode



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.



Improved Support for Binary Attachments…

� 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



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.




� 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 150 0 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.




� 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>



NotesTo 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/>




� 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




�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



Notesapphandler_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>




� 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



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



Descriptionand DiscoveryWS-Policy

WS-ReliableMessaging

UDDI


Transport

BusinessProcesses


Business Process Execution Language

WSDL

SOAP, SOAP Attachments

XML

Transports

WS-Coordination

WS-Transactions

WS-Security Qualityof Service

Web Services and Security

WS-SecurityPolicy WS-Privacy

WS-SecureConversation WS-Authorization

X509profile

Kerberosprofile

XrMLprofile

Usernameprofile

Mobileprofile

SAMLprofile

WS-Security (framework)

WS-Trust

WS-Federation



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



NotesCICS® 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.



CICS Transaction Server 3.1…

� 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



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.



CICS Transaction Server 3.1…

� 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



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



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



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



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.



CICS Support of WS-Trust…

� <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



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.




� 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



Notes

trust mode Meaning

none none No credentials are added to the message

basic Invalid combination of attribute values

signature Asserted identity is not used. CICS uses a single X.509 securitytoken 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




� Service requestor (outbound) attributes…

– trust=basic

• mode=none– Invalid combination of attributes

• mode=basic– Invalid combination of attributes

• mode=signature– Invalid combination of attributes



Notes

trust mode Meaning

basic (any) Invalid combination of attribute values





– trust=blind


• 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




Notes

trust mode Meaning

blind none Invalid combination of attribute values

basic 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 task’s user ID).

signature Invalid combination of attribute values





– trust=signature


• 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>




Notes

trust mode Meaning

signature none Invalid combination of attribute values

basic Asserted identity is used. CICS adds the following tokens to themessage: 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 task’s user ID).

signature Invalid combination of attribute values




� 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



Notes

trust mode Meaning

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

basic Inbound messages must contain a username security token with a password. CICS puts the username in the DFHWS-USERID container.

signature Inbound messages must contain an X.509 security token that has been used to sign the message body.




� Service provider (inbound) attributes…– trust=basic


• 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



Notes

trust mode Meaning

basic none Invalid combination of attribute values

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

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




� Service provider (inbound) attributes…– trust=blind


• 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



Notes

trust mode Meaning

blind none Invalid combination of attribute values

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

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




� Service provider (inbound) attributes…– trust=signature


• 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



Notes

trust mode Meaning

Signature none Invalid combination of attribute values

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

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




� <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 The STS issues an identity token for the SOAP message.

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




� 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



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.




� 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



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



CICS Web Services Assistants

� 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



NotesThere 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|CURR ENT} 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.



CICS Web Services Assistants…� 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



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.



CICS Web Services Assistants…

� Support for WSDL 2.0

– 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



NotesWSDL_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 parameterforces the minimum runtime level to 2.0 regardless of the mapping level specified (in much thesame 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 toSOAP 1.1. If WSDL 2.0 is required (and not 1.1) then it defaults to SOAP 1.2. If both WSDL 1.1and 2.0 are required then it defaults to generating Bindings suitable for both SOAP 1.1 and SOAP1.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).



NotesDFHWS2LS 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:Operationelements 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

– Name – Configuration file – Shelf directory – WSBIND directory – Use count

� Web Service statistics

– Name – Program interface – Message validation – PIPELINE name – URIMAP name – WSBIND file – WSDL file – Porttype– Endpoint – Program name – Use count



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


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


The Two CICS Models of SOA Integration

CICS TS

Web Service Client

CICSWeb

Servicessupport

Integration logic

Dataaccess

Business Function

DI

Business logic

B

Other/Any (Service Provider)

CICS TS

Web Service Client

CICS Program

Business logic

B

Other/Any

connectorWeb services end-point

Intermediary

A


Strategic Connectors

� Standard architectures provide comprehensive development tools and runtime support in CICS

Web services over SOAP (Simple Object Access Protocol)

J2C (J2EE Connector Architecture)

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 archi tectures. These applications will assume more responsibility for sy stems management, security, and recovery

HTTP (HyperText Transfer Protocol)

WebSphere MQ (MQ APIs or JMS - Java Messaging Service)

TCP/IP sockets

1

4

5

6

3

2


CICS TS

Access to CICS – Strategic Connectors

Web services

Web Service Implementation

J2C

Web services

1

4

5

6

3

2

Intermediary Server

DB

A

I

HTTP

WMQ

Sockets

RMI


Access from CICS – Strategic Connectors

CICS TS

1

5

6

4

3B

A

Web services

EJBServicerequester

Intermediary Server

Web service

HTTP

Sockets

WMQ


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 s everal e-business clients



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



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



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 su pport




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 anexisting 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 andproblem 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.

manual web services and cics

Documents