1 / 41

Introduction to CICS Web Services

This session provides an introduction to CICS Web Services, covering topics such as artifacts, transports, message handler pipelines, and resource definitions. Learn how CICS can act as both a service provider and requester, and explore examples of SOAP messages and CICS as a service provider and requester. Discover the resources available for CICS as a service provider and requester, including language copybooks, WSDL generation, and the Web Services assistant.

darlenea
Download Presentation

Introduction to CICS Web Services

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

  1. Web Services Steve Zemblowski zem@us.ibm.com

  2. Session Agenda • Web Services introduction • CICS Web Services artifacts • Transports • Message handler pipeline • Web Service binding file • Resource definitions • TCPIPSERVICE • URIMAP • PIPELINE • WEBSERVICE • Summary

  3. Web Services Introduction • What is a Web Service? • A Web Service is an interface: • Describes a collection of operations • Is network accessible • Uses standardized XML messaging • A Web Service is described: • Using standard, formal XML notion (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

  4. Service Registry Service Requester Bind Service Provider Find Publish 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

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

  6. Web Services Introduction… • An example of a SOAP message

  7. Web Services Introduction… • CICS as a Service Provider CICS Transaction Server Web Services Requester CICS Web Services CICS Application Program COMMAREA or Channel <XML SOAP message>

  8. Web Services Introduction… • CICS as a Service Requester CICS Transaction Server CICS Application Program CICS Web Services Web Services Requester COMMAREA or Channel <XML SOAP message>

  9. CICS Web Services • CICS provides a number of artifacts for Web Services • Resource definitions • Transport definitions • TCPIPSERVICE (HTTP) • QLOCAL (WebSphere MQ) • URIMAP • PIPELINE • WEBSERVICE • Message handler pipelines • Provider and requester • SOAP 1.1 and 1.2 • Web services assistant to: • Generate language copybooks from WSDL • Generate WSDL from language copybooks • Generate Web Service binding file

  10. Resources for CICS as a service provider CICS TS V3.1 TCPIPSERVICE CSOL SOAP message CPIH CWXN Service Requester Pipeline URIMAP matching handlers URIMAP HFS handlers dynamic install pipeline config handlers WSDL PIPELINE data mapping CICS provided utility dynamic install Business Logic WSBind WEBSERVICE Language structure

  11. Resources for CICS as a service requester CICS TS V3.1 User Transaction Language structure Business Logic HFS WEBSERVICE WSBind data mapping CICS provided utility Pipeline dynamic install PIPELINE WSDL handlers pipeline config handlers handlers Service Provider SOAP message

  12. CICS Web Services… • 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

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

  14. WMQ definition Target service will flow in the MQ RFH2 header Format is ‘/string’ Matching occurs on URIMAP path Default target service Used if not specified in request Define the input queue DEFINE QLOCAL ('queuename') DESCR ('description') PROCESS(processname) INITQ('initqueue') TRIGGER TRIGTYPE(FIRST) TRIGDATA('default target service') BOTHRESH(nnn) BOQNAME('requeuename') CICS Web Services…

  15. CICS Web Services… • 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 • Only uses PATH (webservice/identifier) for matching • SCHEME can be (*) • HOST can be (*) • TCPIPSERVICE (optional) • 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 • USERID • Userid under which the web service will execute

  16. CICS Web Services… • 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) ==> ==> ==> ==>

  17. CICS Web Services… • WEBSERVICE definition • Defines the processing nodes 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 • WSDL file needs to be available for validation (YES) WEBSERVICE ==> Group ==> Description ==> Pipeline ==> (Mixed Case) ==> ==> ==> ==> WSBIND ==> (Mixed Case) ==> ==> ==> ==> WSDLFILE ==> (Mixed Case) ==> ==> ==> VALIDATION ==> NO NO|YES

  18. Web Service Resource Interrelationships CICS URIMAP USAGE(PIPELINE) HOST PATH PIPELINE WEBSERVICE HFS PIPELINE config CONFIGFILE SHELF WSDIR dynamic install COMMAREA structure pick-up directory WEBSERVICE WSBind PIPELINE WSBIND WSDLFILE WSDL2CICS WSDL BINDING= URI= PGMNAME= PGMINT=

  19. CICS Web Services… • Pipeline configuration file • XML file that describes: • The mandatory <service> and optional <transport> elements • The sequence of message handlers to be invoked • Different qualities of service will require different configuration files • Service provider • Service requester • SOAP 1.1 • SOAP 1.2 • WS-Security processing • WS-AT (atomic transactions) • User message handlers • e.g. Extract USERID from the message

  20. Service Transport Default HTTP Transport Handler List Default Transport Handler List Default MQ Transport Handler List Handler Handler Handler Service handler list Service handler list handler handler CICS SOAP 1.1 handler CICS SOAP 1.1 handler CICS SOAP 1.2 handler CICS SOAP 1.2 handler CICS Web Services… • Pipeline structure for a service provider Provider Pipeline AppHandler Service Parameter List

  21. CICS Web Services… • Pipeline XML configuration for a service provider <?xml version="1.0" ?> <p:provider_pipeline xmlns:p="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/pipeline/Provider.xsd "> <p:service> <!-- Define the terminal handler for this request - mandatory element --> <p:terminal_handler> <!-- Define the terminal handler to be a CICS supplied 1.1 handler --> <p:cics_soap_1.1_handler/> </p:terminal_handler> </p:service> </p:provider_pipeline>

  22. Transport Default Transport Handler List Default HTTP Transport Handler List Default MQ Transport Handler List Handler Handler Handler Service handler list handler CICS SOAP 1.1 handler CICS SOAP 1.2 handler CICS Web Services… • Pipeline structure for a service requestor Requestor Pipeline Service Service Parameter List

  23. CICS Web Services… • Pipeline XML configuration file for a service requester <?xml version="1.0" ?> <p:requester_pipeline xmlns:p="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/pipeline/Requester.xsd "> <p:service> <p:service_handler_list> <!-- Define a single service handler as a CICS supplied SOAP handler --> <p:cics_soap_1.1_handler/> </p:service_handler_list> </p:service> </p:requester_pipeline>

  24. CICS Web Services… • Message Handlers • Program to process a request during input or a response during output • An example might be to log the message • Functions • Examine the contents of an XML request or response, without changing it • Change the contents of an XML request or response • In a non-terminal message handler, pass an XML request or response to the next message handler in the pipeline • In a terminal message handler, call an application program, and generate a response • In the request phase of the pipeline, force a transition to the response phase, by absorbing the request, and generating a response • Handle errors • Use channels and containers • Between CICS and the message handler • Between message handlers

  25. CICS Web Services… • Channel structure • All message handlers are invoked with a channel with a number of containers • Container structure • Control containers • Control operation of the pipeline • Used to modify the sequence of the pipeline • Context containers • Holds information about the context in which the message handler is invoked (e.g. name of pipeline resource for this program) • User containers • Used to pass information between message handlers • e.g. pass state data

  26. CICS Web Services… • Control containers • DFHFUNCTION • Specifies the reason that a handler is being invoked • DFHREQUEST • Conveys an XML request message between message handlers • DFHRESPONSE • Conveys an XML response message between message handlers • DFHNORESPONSE • A service provider is NOT expected to send a response • A service requester does not require a response • DFHERROR • Conveys error information between message handlers

  27. CICS Web Services… • Context containers • DFHWS-URI • URI of the incoming service request • DFHWS-TRANID • Transaction ID of the task in the pipeline • DFHWS-USERID • USERID of the task in the pipeline • DFHWS-APPHANDLER • Name of the <apphandler> element or the target application program • DFHWS-PIPELINE • Name of the PIPELINE resource definition for this program • DFHWS-WEBSERVICE • Name of the matched WEBSERVICE definition • DFH-SERVICEPLIST • Contents of <service_parameter_list> element • DFH-HANDLERPLIST • Contents of the appropriate <handler_parameter_list> for the SOAP handler

  28. CICS Web Services… • SOAP message handlers • CICS provided message handlers to process SOAP messages • SOAP 1.1 and 1.2 • Input processing • Extract the <Body> for use by your application program • Output processing • Construct the complete SOAP message using the <Body> element from your application program • CICS SOAP message handlers can invoke user written header processing programs • Examine the message and the header on input and output messages • Add headers to outbound messages

  29. CICS Web Services… • User-written header processing programs • Process SOAP header blocks with CICS provided pipelines • Invoked with a Channel and containers • Message handlers may contain <headerprogram> elements • <headerprogram> elements have children • <program_name> • <namespace> • <localname> • <mandatory> • Header processing program invoked when: • URI match occurs • <Mandatory> true is specified

  30. CICS Web Services… • Pipeline XML configuration file for a service provider • Defining a program to handle a header block <?xml version="1.0" ?> <p:provider_pipeline xmlns:p="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/pipeline ../Schema/NewProvider.xsd "> <p:service> <!-- Define the terminal handler for this request - mandatory element --> <p:terminal_handler> <!-- Define the terminal handler to be a CICS supplied 1.1 handler --> <p:cics_soap_1.1_handler> <p:headerprogram> <!-- Define the program that will be executed to deal with this header --> <p:program_name>MYPROG1</p:program_name> <!-- Define the namespace for this header - used to match incoming requests --> <p:namespace>http://www.ibm.com/whatever</p:namespace> <!-- Define the local name of this header - used to match incoming requests --> <p:localname>myHeader</p:localname> <!-- Define whether it is mandatory to run this header handler every request --> <p:mandatory>false</p:mandatory> </p:headerprogram> </p:cics_soap_1.1_handler> </p:terminal_handler> </p:service> </p:provider_pipeline>

  31. CICS Web Services… • SOAP node interfaces • Header handler interface • Passes information between the SOAP node and the header handler program • Application handler interface • Passes information between the SOAP node and an application handler

  32. CICS Web Services… • SOAP header processing interface • Channel DFHHHC-V1 passed to both SOAP 1.1 and 1.2 nodes • Containers • DFHHEADER • Header block that caused the handler to be driven • DFHWS-XMLNS • Information about the name space • DFHWS-BODY • Body of the SOAP envelop • DFHFUNCTION • Reason the SOAP handler was invoked • Any user containers created in the channel

  33. CICS Web Services… • SOAP application handler interface • Channel DFHAHC-V1 passed to the application handler • Containers • DFHWS-XMLNS • Name-value pairs that map namespace prefixes to namespaces • DFHWS-BODY • Body of the SOAP envelope • DFHNORESPONSE • Indication from application handler that no response is to be generated • Any user containers created in the channel

  34. CICS Web Services… • Programming Interfaces • Fault Processing • SOAP <Fault> is used to carry error information • Contained in the body of a message • SOAP 1.1 Fault sub elements • <faultcode> Error information for software processing • <faultstring> Error information for a human reader • <faultactor> URI of the SOAP node that caused the fault • <details> Application specific error information related to <Body> • SOAP 1.2 Fault sub elements • <Code> Error information for software processing • <Reason> Error information for a human reader • <Node> URI of the SOAP node that caused the error • <Role> Role the node was in when the error occurred • <Details> Application specific error information

  35. CICS Web Services… • Programming Interfaces • Fault Processing • EXEC CICS SOAPFAULT CREATE FAULTCODE ( ) FAULTSTRING ( ) FAULTSTRLEN ( ) ROLE ( ) ROLELENGTH ( ) FAULTACTOR ( ) FAULTACTLEN ( ) DETAIL ( ) DETAILLENGTH ( ) NATLANG ( ) • Create a SOAP fault • EXEC CICS SOAPFAULT ADD SUBCODEST ( ) SUBCODELEN ( ) FAULTSTRING ( ) FAULTSTLEN ( ) NATLANG ( ) • Add a reason to an existing fault in a specified language • EXEC CICS SOAPFAULT DELETE • Delete a Soap Fault that has been created

  36. CICS Web Services… • Programming Interfaces • Invoking a Web Service from a CICS application program • CICS as a service requester • EXEC CICS INVOKE WEBSERVICE ( ) CHANNEL ( ) URI ( ) OPERATION ( ) • WEBSERVICE: name of the Web Service to be invoked • CHANNEL: name of the channel containing data to be passed to the Web Service (DFHWS-DATA container) • URI: Universal Resource Identifier of the Web Service (optional) • OPERATION: name of the operation to be invoked • Invoking a pipeline without invoking a web service • EXEC CICS LINK PROGRAM (DFHPIRT) • Setting up the Channel and Container structure

  37. Web Services Statistics… PIPELINE 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

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

  39. CICS Web Services Monitoring • New field WBIWSSCT • Number of INVOKE WEBSERVICE requests for this task • Added to monitoring group DFHWEBB

  40. CICS Web Services • Expose an existing application as a Web Service • Usage is: SOAP over http 1. Generate the WSBIND and WSDL files (Developer) 2. Create a TCPIPService definition (Systems Programmer) 3. Create the PIPELINE resource definition (Systems Programmer) 4. Install TCPIPSERVICE and PIPELINE definitions (Systems Programmer) Use the PIPELINE Pickup directory to automatically install the URIMAP and WEBSERVICE definitions. 5. Publish WSDL to clients (Developer)

  41. 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 and problem determination support

More Related