web services for the systems programmer

8/3/2019 Web Services for the Systems Programmer

1/68

IBM Software Group

IBM Corporation

IBM CICS Transaction Server for z/OS V3.2Web Services for the Systems Programmer

Steve ZemblowskiCICS Advanced Technical Support

[email protected]


2/68

IBM Software Group

2

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 optionsyou need to support this application request?

This presentation will help you understand the questions you need to ask to determine the qualities ofservices for this CICS Web Services implementation. Knowing the required qualities of service requiredwill enable you to define the appropriate CICS resources and set the correct configuration options.


3/68

IBM Software Group

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 ofSun Microsystems, Inc. in the United States, other countries, or both.

Microsoft, Windows, and the Windows logo are trademarks ofMicrosoft 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.


4/68

IBM Software Group

4

NotesThis page intentionally left blank.


5/68

IBM Software Group

5

Agenda

How to determine the required Qualities of Service

Questions to ask

Configuration and resource definition

Base configuration

Transport definition

Locating the web serviceQuality of service

Documentation

Summary


6/68

IBM Software Group

6

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. Thereare a series of questions that must be answered to supply the information needed by the systemsprogrammer.

There are some base configuration options needed to allow CICS to support Web Services. In additionto 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 ofservice for this set of web services (PIPELINE definition), a definition needed to locate the web servicein 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 Centeras well as two Red Books on CISC Web Services.

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


7/68

IBM Software Group

7

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?

CICS asprovider

Web serviceprovider

Web servicerequester

CICS as

requesterCICS


8/68

IBM Software Group

8

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


9/68

IBM Software Group

9

How to Determine Quality of ServiceRequirements

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?


10/68

IBM Software Group

10

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 servicerequests

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


11/68

IBM Software Group

11


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?


12/68

IBM Software Group

12

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 youconfigure 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 TS32, 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.


13/68

IBM Software Group

13


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?


14/68

IBM Software Group

14

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 WebServices 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 applicationprogram 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 someclients placed user identification (e.g. USERID) information in the SOAP header. Application processing information

should not be placed in the SOAP header.


15/68

IBM Software Group

15

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


16/68

IBM Software Group

16

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 thatyou 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 partof your startup list.


17/68

IBM Software Group

17

CICS as a Service ProviderSystems Programmer Responsibilities

HTTP transport

HFS

WSDL

WSBind

CICS Web servicesassistant

WEBSERVICE

pipelineconfig

URIMAP

CICS TS V3TCPIPSERVICE

CPIHCWXNService

Requester

URIMAPmatching

CSOL

Pipeline

handlers

handlers

handlers

SOAP message

data mapping

Business

Logic

Languagestructure

dynamicinstall

dynamicinstall

PIPELINE


18/68

IBM Software Group

18

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

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

There are new message handler and SOAP header handler programs to augment the standard

processing options.


19/68

IBM Software Group

19

CICS as a Service ProviderDefine the Transport


ServiceRequester

CSOLSOAP message

HTTP

CICS TS V3QLOCAL

ServiceRequester

CKTI

SOAP message

MQ


20/68

IBM Software Group

20

Notes This chart shows the components involved in listening for a web service request to enter CICS over

HTTP or MQ.


21/68

IBM Software Group

21


TCPIPSERVICE definition

Required when CICS is a service

provider

URIMAP matching will occur whenprotocol (HTTP) is specified

Some parameters ignored

URM

Transaction


22/68

IBM Software Group

22

A TCPIPSERVICE definition is required when CICS is the service provider and the chosen transportis 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 matchedagainst the URI. If a match is found (it better be for Web Services) then some parameters will be takenfrom the URIMAP definition instead of the TCPIPSERVICE definition.

Notes


23/68

IBM Software Group

23


Define an MQ initiation queue

Define a local request queue

Required when CICS is the serviceprovider

Pick the URI target up from the RFH2header if present, otherwise default to

trigger data

Define an MQ process object

DEFINE

QLOCAL(queuename)

DESCR(description)

PROCESS(processname)

INITQ(initqueue)

TRIGGERTRIGTYPE(FIRST)

TRIGDATA(path part of URI)

BOTHRESH(nnn)

BOQNAME(requeuename)


24/68

IBM Software Group

24

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

1. Define an initiation queue. Use the following command: DEFINE

QLOCAL('initiation_queue')

DESCR('description')

where initiation_queueis the same as the value specified in IQ= in DFHMQPRM in the INITPARM system initialization parameter.2. For each local request queue, define a QLOCAL object. Use the following command:

DEFINE

QLOCAL('queuename')

DESCR('description')


INITQ('initiation_queue')

TRIGGER

TRIGTYPE(FIRST)

TRIGDATA('default_target_service')

BOTHRESH(nnn)

BOQNAME('requeuename')

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


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.

Notes


25/68

IBM Software Group

25

CICS as a Service ProviderMatching the URI

URIMAP


CWXNService

Requester

URIMAPmatching

CSOLSOAP message

URIMAP

CICS TS V3QLOCAL

CPILServiceRequester

URIMAPmatching

CKTISOAP message


26/68

IBM Software Group

26

This chart shows the URIMAP matching process.

Notes


27/68

IBM Software Group

27

CICS as a Service ProviderWeb Service Resource Interrelationships

HFS

WSBind

WSDL

WEBSERVICEPIPELINEWSBINDWSDLFILE

PIPELINECONFIGFILESHELF

WSDIR

config

URIMAPUSAGE(PIPELINE)HOSTPATH

PIPELINEWEBSERVICE

dynamicinstall

pick-up directory

CICS

dynamicinstall


28/68

IBM Software Group

28

This chart shows the interrelationships between the CICS resource definitions necessary to supportWeb 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 beproduced. The WSBIND file contains information about the CICS program to be invoked, the name ofthe WSDL file, the local URI and information necessary to populate a COMMAREA from XML and viceversa. 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. TheWEBSERVICE 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.

Notes


29/68

IBM Software Group

29

CICS as a Service ProviderDefining the URI

URIMAP definition

Locates the Web Service and the Pipeline resources required toprocess 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 thisrequest

TRANSACTION

Alias transaction for the Web Service


30/68

IBM Software Group

30

The URIMAP definition is used to match a URI to a WEBSERVICE definition and a PIPELINEdefinition. 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 andthat 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 namedTCPIPSERVICE is specified then only requests from that specific port will be matched against thisURIMAP definition.

The PIPELINE parameter names an installed PIPELINE resource which will be used to determinethe 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 executionenvironment 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 beused to run the user application that composes a response to the web service request.

Notes


31/68

IBM Software Group

31

CICS as a Service ProviderDefining the Pipeline

HFS

WSDL

WSBind

WEBSERVICE

pipeline

configURIMAP

CICS TS V3

CPIH/CPIQ

Pipeline

handlers

handlers

handlers

PIPELINE

Application Handler

Target Program


32/68

IBM Software Group

32

The chart shows an example of the pipeline flow.

Notes


33/68

IBM Software Group

33

CICS as a Service ProviderDefining 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 processingnodes that will act on a service request and on theresponse

SHELF

HFS directory for CICS use

WSDIR

Name of the Web service binding directory

HFS pickup directory


34/68

IBM Software Group

34

A PIPELINE resource definition is used when a CICS application is in the role of a Web service provider or requester. Itprovides information about the processing nodes which will act on a service request and on the response. Typically, asingle PIPELINE definition defines an infrastructure that can be used by many applications. There will be separateconfiguration 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 HFSconfiguration 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 intowhich the PIPELINE definition is installed must have full permissions to the shelf directory--read, write, and the abilityto create subdirectories. A single shelf directory may be shared by multiple CICS regions and by multiple PIPELINEdefinitions. Within a shelf directory, each CICS region uses a separate subdirectory to keep its files separate from thoseof 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 notattempt to modify the contents of a shelf that is referred to by an installed PIPELINE definition. If you do, the effects areunpredictable

The Web service binding directory (WSDIR) contains Web service binding files that are associated with a PIPELINE, andthat are to be installed automatically by the CICS scanning mechanism. When the PIPELINE definition is installed, CICSscans the directory and automatically installs any Web service binding files it finds there. Note that this happens regardlessof whether the PIPELINE is installed in enabled or disabled state. A CEMT PERFORM PIPELINE SCAN command can beused 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 witha PIPELINE resource by the URIMAP resource. The URIMAP identifies the PIPELINE resource that applies to the URIassociated with the request; the PIPELINE specifies the processing that is to be performed on the message.

Notes


35/68

IBM Software Group

35

CICS as a Service ProviderDefining the Pipeline Configuration File

Pipeline configuration file

XML file that describes: The mandatory and optional 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

IBM S f G


36/68

IBM Software Group

36

The Pipeline configuration file, named in a PIPELINE resource definition, is used to describe theseries of message handlers (i.e. the pipeline) to process the request. The configuration file is anXML document, stored in HFS and can be edited with any XML editor.

The configuration file will contain mandatory and optional elements alongwith application handler and a service parameter list .

Different applications will require different configuration files. There are different pipelineconfigurations necessary for a service provider and service requester as well as differentconfigurations for processing SOAP 1.1 and 1.2 messages. CICS provides the configurationfiles 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 examplewould be a user message handler to extract user identification from the message to determinewhich USERID and transaction id should be used to process the message.

Notes

IBM S ft G


37/68

IBM Software Group

37


:

:

DFHPITP

Pipeline Controller

apphandler

handler

handler

handler

handler

handler

handler

handler

handler

handler

C

HANNE

L

IBM Software Group


38/68

IBM Software Group

38

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

Notes

IBM Software Group


39/68

IBM Software Group

39

CICS as a Service ProviderDefining 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 thisWEBSERVICE 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 againstWSDL schema

IBM Software Group


40/68

IBM Software Group

40

A WEBSERVICE resource defines the execution environment that lets a CICS application programoperate as a Web service provider or requester. The Web service interaction in which the CICSapplication participates uses SOAP messaging, and is formally described with Web servicedescription language (WSDL).

The execution environment contains three components that are specified in the WEBSERVICEattributes:

A pipelineA Web service binding fileA Web service description

Although CICS provides the usual resource definition mechanisms for creating WEBSERVICEresources, and installing them in your CICS region, there is an alternative strategy which you canuse. You can use the scanning mechanism to install WEBSERVICE resources in your running CICSregion.

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 againstits 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 withrespect to the XML schema. If VALIDATION(NO) is specified, sufficient validation is performed toensure that the message contains well-formed XML.

Notes

IBM Software Group


41/68

IBM Software Group

41

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 WEBSERVICEresource

CICS will also dynamically create a URIMAP definition

IBM Software Group


42/68

IBM Software Group

42

Setting up the CICS resources is not as difficult as it might seem. It is only necessary to define theTCPIPSERVICE (or WMQ) and the PIPELINE. Place the WSBind file generated from the batch toolinginto the HFS directory specified in the PIPELINE definition. Then either issue a CEMT PERFORMPIPELINE 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 theWSBind file, CICS will dynamically create the Web Service resource definition. This provides CICSwith enough information to be able dynamically to create a URIMAP definition as well. So, as longas you create a valid PIPELINE definition and put the WSBind file in the correct location, CICS willdo the rest.

Notes

IBM Software Group


43/68

p

43

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

IBM Software Group


44/68

p

44

When the terminal handler of a service provider pipeline is one of the CICS-supplied SOAP messagehandlers, the target application handler program specified in container DFHWS-APPHANDLER is, in somecases, eligible for dynamic routing. All pipeline processing prior to the application handler program isalways 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 switchprovides an opportunity for dynamic routing to take place, but only if MRO is used to connect the CICSregions together. In addition, the CICS region that you are routing to must support channels andcontainers.

Notes

IBM Software Group


45/68

45

Context Switching

When the terminal handler is a CICS SOAPHandler it is possible to context switch theApplication Handler

If DFHWS-TRANID or DFHWS-USERID

have been changed from the default then the newvalues will be used for a new task to run thebusiness logic

If the values are unchanged the logic would run inthe pipeline task as normal

CHA

NNEL

Pipeline Controller

handler

handler

handler

handler

handler

handler

handler

Pipeline-specified Context

IBM Software Group


46/68

46

The transaction that runs the target application handler program is eligible for routing when one of thefollowing is true:

- The transaction under which the pipeline is processing the message is defined as DYNAMIC orREMOTE. This transaction is defined in the URIMAP that is used to map the URI from the inbound SOAPmessage.

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

Notes

IBM Software Group


47/68

47

CICS as a Service RequesterSystems Programmer Responsibilities

CICS TS V3User Transaction

data mapping

Business Logic

Pipeline

handlers

handlers

handlers

PIPELINE

WEBSERVICE

dynamic

install

HFS

WSBind

WSDL

pipelineconfig

CICS Web services

assistant

ServiceProvider

SOAP message

Languagestructure

EXEC CICS INVOKE

WEBSERVICE

IBM Software Group


48/68

48

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

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

There are new message handler and SOAP header handler programs to augment the standardprocessing options.

IBM Software Group


49/68

49

CICS as a Service RequesterWeb Service Resource Interrelationships

HFS

WSBind

WSDL

WEBSERVICEPIPELINEWSBINDWSDLFILE

PIPELINECONFIGFILESHELF

WSDIR

config

dynamicinstall

pick-up directory

CICS

IBM Software Group


50/68

50

This chart shows the interrelationships between the CICS resource definitions necessary to supportWeb Services.

The CICS WSDL utility will produce a WSDL file from a language structure (copybook) or a languagestructure 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 ofthe WSDL file, the local URI and information necessary to populate a COMMAREA from XML and viceversa. 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. TheWEBSERVICE 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.

Notes

IBM Software Group


51/68

51

CICS as a Service RequesterDefining 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 processingnodes that will act on a service request and on theresponse

SHELF

HFS directory for CICS use

WSDIR

Name of the Web service binding directory

HFS pickup directory

IBM Software Group


52/68

52

A PIPELINE resource definition is used when a CICS application is in the role of a Web service provider or requester. Itprovides information about the processing nodes which will act on a service request and on the response. Typically, asingle PIPELINE definition defines an infrastructure that can be used by many applications. There will be separateconfiguration 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 HFSconfiguration 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 intowhich the PIPELINE definition is installed must have full permissions to the shelf directory--read, write, and the abilityto create subdirectories. A single shelf directory may be shared by multiple CICS regions and by multiple PIPELINEdefinitions. Within a shelf directory, each CICS region uses a separate subdirectory to keep its files separate from thoseof other CICS regions. Within each region's directory, each PIPELINE uses a separate subdirectory. After a CICS regionperforms 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 areunpredictable

The Web service binding directory (WSDIR) contains Web service binding files that are associated with a PIPELINE, andthat are to be installed automatically by the CICS scanning mechanism. When the PIPELINE definition is installed, CICSscans the directory and automatically installs any Web service binding files it finds there. Note that this happens regardlessof whether the PIPELINE is installed in enabled or disabled state. A CEMT PERFORM PIPELINE SCAN command can beused 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 witha PIPELINE resource by the URIMAP resource. The URIMAP identifies the PIPELINE resource that applies to the URIassociated with the request; the PIPELINE specifies the processing that is to be performed on the message.

Notes

IBM Software Group


53/68

53

:

:

:


CHAN

NEL

Pipeline Controller

handler

handler

handler

handler

handler

handler

Transport

IBM Software Group


54/68

54

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

IBM Software Group


55/68

55

CICS as a Service RequesterDefine the Transport

HTTP or HTTPS

No definition required

MQDefine the reply-to queue

IBM Software Group


56/68

56

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.

Notes

IBM Software Group


57/68

57

CICS as a Service ProviderDefining the Web Service

WEBSERVICE definition

Defines the application specific details for aweb service request

Defines the execution environment for WebService application

PIPELINE

Name of the pipeline where thisWEBSERVICE 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 againstWSDL schema

IBM Software Group


58/68

58

A WEBSERVICE resource defines the execution environment that lets a CICS application programoperate as a Web service provider or requester. The Web service interaction in which the CICSapplication participates uses SOAP messaging, and is formally described with Web servicedescription language (WSDL).

The execution environment contains three components that are specified in the WEBSERVICEattributes:

A pipelineA Web service binding fileA Web service description

Although CICS provides the usual resource definition mechanisms for creating WEBSERVICEresources, and installing them in your CICS region, there is an alternative strategy which you canuse. You can use the scanning mechanism to install WEBSERVICE resources in your running CICSregion.

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 againstits 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 withrespect to the XML schema. If VALIDATION(NO) is specified, sufficient validation is performed toensure that the message contains well-formed XML.

Notes

IBM Software Group


59/68

59

Web Services StatisticsPIPELINE Name. . . . . . . . . : DFHWSATP

PIPELINE Enable Status . . . . : Disabled

Configuration file . . . . . . :

/usr/lpp/cicsts/pipeline/configs/registrationservicePROV.xml

Shelf directory. . . . . . . . : /var/cicsts/

WSDIR pickup directory . . . . :

PIPELINE use count . . . . . . : 0

-------------------------------------------------------------------------------

PIPELINE Name. . . . . . . . . : DFHWSATR

PIPELINE Enable Status . . . . : Disabled

Configuration file . . . . . . :

/usr/lpp/cicsts/pipeline/configs/registrationserviceREQ.xml

Shelf directory. . . . . . . . : /var/cicsts/WSDIR pickup directory . . . . :

PIPELINE use count . . . . . . : 0

IBM Software Group

Notes


60/68

60

Notes

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

IBM Software Group

S S


61/68

61

Web Services Statistics

WEBSERVICE Name . . . . . . . . . : TESTCJB

WEBSERVICE Status . . . . . . . . : Unusable

Last modified date and time . . . :

URIMAP name . . . . . . . . . . . :

PIPELINE name . . . . . . . . . . : PIPESAMP

Web service description (WSDL). . :

Web service binding file. . . . . : /u/dbeard1/wsbind/CPYBEARD

Web service WSDL binding. . . . . :

Endpoint. . . . . . . . . . . . . :

Validation. . . . . . . . . . . . : Yes

Program interface . . . . . . . . :

Program name. . . . . . . . . . . :

Container . . . . . . . . . . . . :

WEBSERVICE use count. . . . . . . : 0

IBM Software Group

Notes


62/68

62

Notes

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

IBM Software Group

CICS W b S i M it i


63/68

63

CICS Web Services Monitoring

New field WBIWSSCT

Number of INVOKE WEBSERVICE requests for this task

Added to monitoring group DFHWEBB

IBM Software Group

Notes


64/68

64

Notes

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

IBM Software Group

Documentation


65/68

65

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

IBM Software Group

Notes


66/68

66

References to additional documentation.

Notes

IBM Software Group


67/68

67

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

IBM Software Group

Notes


68/68

68

References to additional documentation.

Notes

web services for the systems programmer

Documents