IBM Software Group

IBM CICS Transaction Server for z/OS V3.2 Web Services for the Systems Programmer
Steve Zemblowski CICS Advanced Technical Support zem@us.ibm.com

IBM Corporation

IBM Software Group

Notes

When your application programmer comes up to you and says We want to do Web Services in CICS do you know what questions to ask? Do you know what resource definitions and configuration options you need to support this application request? This presentation will help you understand the questions you need to ask to determine the qualities of services for this CICS Web Services implementation. Knowing the required qualities of service required will enable you to define the appropriate CICS resources and set the correct configuration options.

IBM Software Group

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.

IBM Software Group

Notes
This page intentionally left blank.

IBM Software Group

Agenda
How to determine the required Qualities of Service
Questions to ask

Configuration and resource definition

Base configuration Transport definition Locating the web service Quality of service

Documentation Summary

IBM Software Group

Notes

This presentation will cover the discussion a systems programmer needs to have with the application programmers to define and configure CICS Web Services support for this specific application. There are a series of questions that must be answered to supply the information needed by the systems programmer. There are some base configuration options needed to allow CICS to support Web Services. In addition to these base options, there are unique resource definitions required for the specific CICS application. There are definitions needed for the transport (http, https or MQ), a definition to specify the quality of service for this set of web services (PIPELINE definition), a definition needed to locate the web service in CICS (URIMAP) and a definition to identify the copybook/XML transformation requirements. There is a CICS Web Services Guide included with the CICS Transaction Server 3.2 Information Center as well as two Red Books on CISC Web Services.

Implementing CICS Web Services SG24-7206 Application Development for CICS Web Services SG24-7126

IBM Software Group

How to Determine Quality of Service Requirements

Will this application be a web service provider or requester? Is this a new or existing CICS application?
How many requests does the application expect to service?

What are the availability requirements of the application?

Web service requester

CICS as provider

CICS

CICS as requester

Web service provider

IBM Software Group

Notes

Will this application be a web service provider or requester?

You need to determine if this is an inbound flow to CICS or an outbound flow from CICS. There will be different resource definitions based on whether this application is a requester or provider.

Is this a new or existing CICS application?

If this is an existing application you will have knowledge of the performance characteristics of this application and should be able to determine whether this will fit within your existing CICS configuration. There is a CICS White paper that discusses how to size the processing requirements of a CICS Web Service application. Please refer to: ftp://ftp.software.ibm.com/software/htp/cics/txppacs/Web_Services_Performance.zip

What are the availability requirements of the application?

If this application will have high availability requirements then you may have to design a CICSplex environment in which to run the application. You may have to have redundant transports to support the application.

IBM Software Group

How to Determine Quality of Service Requirements

What are the transport requirements?
How will the requests flow into or out of CICS? HTTP, HTTP (SSL), MQ If HTTP or HTTPS, what are the port numbers required

What level of SOAP will the application require?

1.1 or 1.2

What level of WSDL will the application be using?

Will the application be using Message Exchange Patterns? How long will the application need to wait for an exception response?

IBM Software Group

Notes

What are the transport requirements?

CICS supports either HTTP/HTTPS or MQ as a base transport. To configure the transport resource definition, TCPIPSERVICE or QLOCAL, you need to understand the port numbers or Queue Names associated with the web service requests

What level of SOAP will the application require?

CICS support either the 1.1 or 1.2 level of SOAP for web service processing. As part of the definition process you do need to define the level of SOAP that the application will require.

What level of WSDL will the application be using?

CICS can support web service requests using the Web Services Description Language 1.1 or 2.0 level. The newer level, WSDL 2.0, supports Message Exchange Patterns. Message Exchange Patterns enforce the specified flows between requester and providers. In some cases, the provider will respond to the requester ONLY if an error occurs. As part of the definition process you will need to know how long to wait for an error to occur before proceeding.

10

IBM Software Group

How to Determine Quality of Service Requirements

What are the transactional requirements of the application?
e.g. Recovery/Restart Is this a local or global transaction?

Will the application be sending or receiving large binary objects?

Does the application expect to handle these binary objects directly?

How will the application handle XML transformations?

Directly or using CICS provided facilities?

11

IBM Software Group

Notes

What are the transactional requirements of the application?

You need to understand the recovery/restart requirements of the CICS web service application. Is this a simple inquiry requests or are resources updated by both the requester and the provider? These requirements will determine how you configure the CICS web service support.

Will the application be sending or receiving large binary objects?

Applications today are sending/receiving large objects such as identification photos, fingerprints, engineering diagrams using web services. Prior to CICS TS 32 these objects were included in the message and encoded in base64. In CICS TS 32, there is support for Message Transmission Optimization Mechanism and XML Optimized Packaging to make the transport and processing of these large objects more efficient. These objects can be a passed directly to the application in binary form or encoded as a base64 variable length field in the message.

How will the application handle XML transformations?

The payload of the request is in XML format. A new application could be written to handle the XML message directly. When reusing an existing application CICS facilities can parse the XML message and place the information into a copybook for use by the application.

12

IBM Software Group

How to Determine Quality of Service Requirements

How will the user identify be established for authentication and authorization?
No security requirement User name token or user name token with password Digital certificate Other

Are they any special handling requirements for the message?

e.g. logging of the original message

Are they any SOAP header processing requirements?

13

IBM Software Group

Notes

How will the user identify be established for authentication and authorization?

One of the more important topics of discussion is security. That is how is the user identification established, authenticated and then how does authorization take place in CICS. There are a number of options available to CICS Web Services from no security to using a security token service, such as TFIM to validate and issue security tokens for use by CICS.

Are there any special handling requirements for the message?

There are a number of places where the XML message can be viewed, changed or rejected prior to the application program getting control. In some installations all inbound and outbound requests are logged. This can be accomplished in a message handler.

Are there any SOAP header processing requirements?

Some web service applications place control information in the SOAP header. These SOAP headers can be processed by prior to the application getting control or after the application has constructed an outgoing message. In the past some clients placed user identification (e.g. USERID) information in the SOAP header. Application processing information should not be placed in the SOAP header.

14

IBM Software Group

CICS Web Services: Base Configuration

Ensure that you have installed LE support for PL/I
CICS-supplied SOAP 1.1 and SOAP 1.2 message handler programs

Activate z/OS Support for Unicode

Enable the z/OS conversion services Specify the data conversions required z/OS Support for Unicode: Using Conversion Services

Install CICS supplied web services resource definitions

DFHPIPE In the supplied DFHLIST

15

IBM Software Group

Notes

Ensure that you have installed LE support for PL/I

PL/I support is also required if you use the Web services support in CICS; in particular, it is required if you use the CICS-supplied SOAP 1.1 and SOAP 1.2 message handler programs.

Activate z/OS Support for Unicode

You must enable the z/OS conversion services and install a conversion image that specifies the data conversions that you want CICS to perform between SOAP messages and an application program. For more information, see z/OS Support for Unicode: Using Conversion Services.

Install CICS supplied web services resource definitions

The CICS transactions and programs to support web services are in group DFHPIPE. Make sure this is installed as part of your startup list.

16

IBM Software Group

CICS as a Service Provider

Systems Programmer Responsibilities
TCPIPSERVICE
SOAP message

CICS TS V3
CPIH
Pipeline

CSOL

Service Requester

CWXN

HTTP transport

URIMAP matching URIMAP

handlers

HFS
pipeline config WSDL
CICS Web services assistant

handlers dynamic install handlers PIPELINE data mapping dynamic install Business Logic

WSBind WEBSERVICE Language structure

17

IBM Software Group

Notes

This diagram shows the CICS components and resource definitions involved in a web service request when CICS is the service provider. The highlighted areas are the responsibility of the CICS systems programmer. There are new and existing resource definitions used to process a web service request

TCPIPSERVICE or QLOCAL URIMAP PIPELINE WEBSERVICE

There is a new pipeline configuration file used to control the activities as CICS process the SOAP request. There are new message handler and SOAP header handler programs to augment the standard processing options.

18

IBM Software Group

CICS as a Service Provider

Define the Transport
HTTP
SOAP message

TCPIPSERVICE CSOL

CICS TS V3

Service Requester

MQ
SOAP message

QLOCAL CKTI

CICS TS V3

Service Requester

19

IBM Software Group

Notes

This chart shows the components involved in listening for a web service request to enter CICS over HTTP or MQ.

20

IBM Software Group

CICS as a Service Provider

Define the Transport
TCPIPSERVICE definition
Required when CICS is a service provider URIMAP matching will occur when protocol (HTTP) is specified Some parameters ignored URM Transaction

21

IBM Software Group

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

22

IBM Software Group

CICS as a Service Provider

Define the Transport
Define an MQ initiation queue Define a local request queue
Required when CICS is the service provider Pick the URI 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)

Define an MQ process object

23

IBM Software Group

Notes
1.

A local WebSphere MQ queue definition is required when CICS is the service provider and the chosen transport is WMQ.

Define an initiation queue. Use the following command: DEFINE QLOCAL('initiation_queue') DESCR('description') where initiation_queue is the same as the value specified in IQ= in DFHMQPRM in the INITPARM system initialization parameter. For each local request queue, define a QLOCAL object. Use the following command: DEFINE QLOCAL('queuename') DESCR('description') PROCESS(processname) INITQ('initiation_queue') TRIGGER TRIGTYPE(FIRST) TRIGDATA('default_target_service') BOTHRESH(nnn) BOQNAME('requeuename')

2.

where: queuename is the local queue name. processname is the name of the process instance that identifies the application started by the queue manager when a trigger event occurs. Specify the same name on each QLOCAL object. initiation_queue is the name of the initiation queue to be used (e.g. as specified in IQ= in the DFHMQPRM INITPARM system initialization parameters for Websphere MQ). default_target_service is the default target service to be used if a service is not specified on the request . 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 '/' . nnn is the number of retries that will be attempted. requeuename is the name of the queue to which failed messages will be sent. 3. Define a PROCESS object that specifies the trigger process. Use the following command: DEFINE PROCESS(processname) APPLTYPE(CICS) APPLICID(CPIL) where: processname is the name of the process, and must be the same as the name that is used when defining the request queues. 24

IBM Software Group

CICS as a Service Provider

Matching the URI
TCPIPSERVICE
SOAP message

CICS TS V3

CSOL

Service Requester

CWXN

URIMAP matching URIMAP

QLOCAL
SOAP message

CICS TS V3

CKTI CPIL

Service Requester

URIMAP matching URIMAP

25

IBM Software Group

Notes
This chart shows the URIMAP matching process.

26

IBM Software Group

CICS as a Service Provider

Web Service Resource Interrelationships
URIMAP USAGE(PIPELINE) HOST PATH PIPELINE WEBSERVICE

CICS

HFS
config

dynamic install PIPELINE CONFIGFILE SHELF WSDIR dynamic install WEBSERVICE PIPELINE WSBIND WSDLFILE

WSBind pick-up directory

WSDL

27

IBM Software Group

Notes
This chart shows the interrelationships between the CICS resource definitions necessary to support Web Services. The CICS WSDL utility will produce a WSDL file from a language structure (copybook) or a language structure from WSDL. As part of the generation process a Web Services Binding file (WSBIND) will be produced. The WSBIND file contains information about the CICS program to be invoked, the name of the WSDL file, the local URI and information necessary to populate a COMMAREA from XML and vice versa. Both the WSBIND and the WSDL file will be used by the executing CICS region. The URIMAP definition will name both the PIPELINE definition and the WEBSERVICE definition. Optionally, the URIMAP can specify an installed TCPIPSERVICE name to restrict the matching to information for the specific port named in that resource definition. The PIPELINE resource definition will copy installed WEBSERVICE definitions to its SHELF. The WEBSERVICE definitions can be dynamically created through the use of the pick-up directory (WSDIR). The WEBSERVICE definition will name the PIPELINE definition that contains the configuration information (CONFIGFILE) on which message handlers are invoked when processing this Web Service.

28

IBM Software Group

CICS as a Service Provider

Defining the URI
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

29

IBM Software Group

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

IBM Software Group

CICS as a Service Provider

Defining the Pipeline
CICS TS V3
CPIH/CPIQ
Pipeline

HFS
handlers pipeline config WSDL PIPELINE WSBind WEBSERVICE handlers
Application Handler Target Program

URIMAP handlers

31

IBM Software Group

Notes
The chart shows an example of the pipeline flow.

32

IBM Software Group

CICS as a Service Provider

Defining the Pipeline
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 processing nodes that will act on a service request and on the response
SHELF

HFS directory for CICS use

WSDIR

Name of the Web service binding directory

HFS pickup directory

33

IBM Software Group

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

34

IBM Software Group

CICS as a Service Provider

Defining the Pipeline Configuration File
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 Message handlers Security Atomic Transactions SOAP header handlers e.g. Extract USERID from the message
35

IBM Software Group

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

36

IBM Software Group

CICS as a Service Provider

Defining the Pipeline Configuration File
<?xml version="1.0" encoding="UTF-8"?> <provider_pipeline xmlns="http://www.ibm.com/software/htp/cics/pipeline" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.ibm.com/software/htp/cics/provider.xsd "> <transport> : </transport> <service> <service_handler_list> : </service_handler_list> <terminal_handler> <cics_soap_1.1_handler/> </terminal_handler> </service> <apphandler>DFHPITP</apphandler> <service_parameter_list /> </provider_pipeline>
37 handler handler handler handler

Pipeline Controller

C H A N N E L
handler apphandler

handler handler handler handler

IBM Software Group

Notes
This chart shows an example of a pipeline configuration file along with the flow thru a set of message handlers.

38

IBM Software Group

CICS as a Service Provider

Defining the Web Service
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

39

IBM Software Group

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

40

IBM Software Group

Setting up the Resource Definitions

Define a TCPIPSERVICE (or WMQ) and a PIPELINE Then either
Manually Define the WEBSERVICE and URIMAP definitions Install the definitions Dynamically Move the WSDL and WSBIND file to the pickup directory Issue CEMT PERFORM PIPELINE SCAN CICS uses the PIPELINE definition to Locate the WSBind file From the WSBind file, CICS will dynamically create a WEBSERVICE resource CICS will also dynamically create a URIMAP definition

41

IBM Software Group

Notes
Setting up the CICS resources is not as difficult as it might seem. It is only necessary to define the TCPIPSERVICE (or WMQ) and the PIPELINE. Place the WSBind file generated from the batch tooling into the HFS directory specified in the PIPELINE definition. Then either issue a CEMT PERFORM PIPELINE SCAN command or definition the WEBSERVICE and URIMAP definitions individually. The PIPELINE definition contains the directory name where the WSBind file can be found. From the WSBind file, CICS will dynamically create the Web Service resource definition. This provides CICS with enough information to be able dynamically to create a URIMAP definition as well. So, as long as you create a valid PIPELINE definition and put the WSBind file in the correct location, CICS will do the rest.

42

IBM Software Group

Dynamic Routing of inbound Web Service Requests

Context Switching
A pipeline provided service used by the CICS supplied SOAP Handlers Allows the application program invoked by the SOAP Handler to run in a different context than the pipeline task e.g. Different transaction id, userid A second task is used to run the application layer program

Request Streams are used to communicate between the two tasks Used by WS-AT support to persist the application task

43

IBM Software Group

Notes
When the terminal handler of a service provider pipeline is one of the CICS-supplied SOAP message handlers, the target application handler program specified in container DFHWS-APPHANDLER is, in some cases, eligible for dynamic routing. All pipeline processing prior to the application handler program is always performed locally in the CICS region that received the SOAP message. The second task runs under the transaction specified in the DFHWS-TRANID container. This task switch provides an opportunity for dynamic routing to take place, but only if MRO is used to connect the CICS regions together. In addition, the CICS region that you are routing to must support channels and containers.

44

IBM Software Group

Context Switching
When the terminal handler is a CICS SOAP Handler it is possible to context switch the Application Handler If DFHWS-TRANID or DFHWS-USERID have been changed from the default then the new values will be used for a new task to run the business logic If the values are unchanged the logic would run in the pipeline task as normal
handler

Pipeline Controller

handler

handler

C H A N N E L
handler

handler

handler

handler

Pipeline-specified Context
45

IBM Software Group

Notes
The transaction that runs the target application handler program is eligible for routing when one of the following is true: - The transaction under which the pipeline is processing the message is defined as DYNAMIC or REMOTE. This transaction is defined in the URIMAP that is used to map the URI from the inbound SOAP message. - A program in the pipeline has changed the contents of container DFHWS-USERID from its initial value. - A program in the pipeline has changed the contents of container DFHWS-TRANID from its initial value. - A WS-AT SOAP header exists in the inbound SOAP message. - An eWLM ARM correllator SOAP header exists in the inbound SOAP message.

46

IBM Software Group

CICS as a Service Requester

Systems Programmer Responsibilities
CICS TS V3
Language structure

User Transaction
Business Logic
EXEC CICS INVOKE WEBSERVICE

HFS
WEBSERVICE dynamic install PIPELINE handlers pipeline config handlers WSDL WSBind
CICS Web services assistant

data mapping Pipeline

handlers Service Provider

SOAP message

47

IBM Software Group

Notes

This diagram shows the CICS components and resource definitions involved in a web service request when CICS is the service requester. The highlighted areas are the responsibility of the CICS systems programmer. There are new and existing resource definitions used to process a web service request

PIPELINE WEBSERVICE

There is a new pipeline configuration file used to control the activities as CICS process the SOAP request. There are new message handler and SOAP header handler programs to augment the standard processing options.

48

IBM Software Group

CICS as a Service Requester

Web Service Resource Interrelationships
CICS

HFS
config PIPELINE CONFIGFILE SHELF WSDIR dynamic install WEBSERVICE PIPELINE WSBIND WSDLFILE

WSBind pick-up directory

WSDL

49

IBM Software Group

Notes
This chart shows the interrelationships between the CICS resource definitions necessary to support Web Services. The CICS WSDL utility will produce a WSDL file from a language structure (copybook) or a language structure from WSDL. As part of the generation process a Web Services Binding file (WSBIND) will be produced. The WSBIND file contains information about the CICS program to be invoked, the name of the WSDL file, the local URI and information necessary to populate a COMMAREA from XML and vice versa. Both the WSBIND and the WSDL file will be used by the executing CICS region. The PIPELINE resource definition will copy installed WEBSERVICE definitions to its SHELF. The WEBSERVICE definitions can be dynamically created through the use of the pick-up directory (WSDIR). The WEBSERVICE definition will name the PIPELINE definition that contains the configuration information (CONFIGFILE) on which message handlers are invoked when processing this Web Service.

50

IBM Software Group

CICS as a Service Requester

Defining the Pipeline
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 processing nodes that will act on a service request and on the response
SHELF

HFS directory for CICS use

WSDIR

Name of the Web service binding directory

HFS pickup directory

51

IBM Software Group

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

52

IBM Software Group

CICS as a Service Provider

Defining the Pipeline Configuration File
<?xml version="1.0" encoding="UTF-8"?> <requester_pipeline xmlns="http://www.ibm.com/software/htp/cics/pipeline" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.ibm.com/software/htp/cics/Reques ter.xsd ">

<service> <service_handler_list> : <cics_soap_1.1_handler/> : </service_handler_list> </service> <transport> : </transport> <service_parameter_list /> </requester_pipeline>

Pipeline Controller

handler

handler handler

C H A N N E L Transport

handler

handler handler

53

IBM Software Group

Notes
This chart illustrates the flow of the message handler invocations when CICS is a service requester.

54

IBM Software Group

CICS as a Service Requester

Define the Transport
HTTP or HTTPS
No definition required

MQ
Define the reply-to queue

55

IBM Software Group

Notes
When using http or http as the outbound transport no definition is required in CICS. When using MQ as the outbound transport the reply-to queue must be known to the local queue manager.

56

IBM Software Group

CICS as a Service Provider

Defining the Web Service
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

57

IBM Software Group

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

IBM Software Group

Web Services Statistics

PIPELINE Name. . . . . . . . . : PIPELINE Enable Status . . . . : DFHWSATP Disabled Configuration file . . . . . . : /usr/lpp/cicsts/pipeline/configs/registrationservicePROV.xml Shelf directory. . . . . . . . : WSDIR pickup directory . . . . : PIPELINE use count . . . . . . : 0 /var/cicsts/

------------------------------------------------------------------------------PIPELINE Name. . . . . . . . . : PIPELINE Enable Status . . . . : DFHWSATR Disabled

Configuration file . . . . . . : /usr/lpp/cicsts/pipeline/configs/registrationserviceREQ.xml Shelf directory. . . . . . . . : WSDIR pickup directory . . . . : PIPELINE use count . . . . . . : 0 /var/cicsts/

59

IBM Software Group

Notes
This is a sample statistics report showing the new Pipeline section.

60

IBM Software Group

Web Services Statistics

WEBSERVICE Name . . . . . . . . . : WEBSERVICE Status . . . . . . . . : Last modified date and time . . . : URIMAP name . . . . . . . . . . . : PIPELINE name . . . . . . . . . . : Web service description (WSDL). . : Web service binding file. . . . . : Web service WSDL binding. . . . . : Endpoint. . . . . . . . . . . . . : Validation. . . . . . . . . . . . : Program interface . . . . . . . . : Program name. . . . . . . . . . . : Container . . . . . . . . . . . . : WEBSERVICE use count. . . . . . . : 0 Yes /u/dbeard1/wsbind/CPYBEARD PIPESAMP TESTCJB Unusable

61

IBM Software Group

Notes
This is a sample statistics report showing the new Web Services section.

62

IBM Software Group

CICS Web Services Monitoring

New field WBIWSSCT
Number of INVOKE WEBSERVICE requests for this task Added to monitoring group DFHWEBB

63

IBM Software Group

Notes
340 (TYPE-A, 'WBIWBSCT', 4 BYTES) The number of CICS Invoke web service requests issued by the user task

64

IBM Software Group

Documentation
CICS Web Services Guide SC34-6838 WebSphere MQ Transport for SOAP SC34-6651 CICS TS Web Services Performance
ftp://ftp.software.ibm.com/software/htp/cics/txppacs/Web_Services_Performance.zip

Red Books
SG24-7206 SG24-7126

65

IBM Software Group

Notes
References to additional documentation.

66

IBM Software Group

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 service requester applications

CICS infrastructure support

EXEC support for outbound calls CICS utilities
WSDL to language structure generation Language structure to WSDL generation XML to COMMAREA mapping

Resource definitions on-line

URIMAP PIPELINE WEBSERVICE

Monitoring & Statistics

67

IBM Software Group

Notes
References to additional documentation.

68