CICS Transaction Server V 3 1 Web Services
CICS Transaction Server V 3. 1 Web Services Steve Zemblowski zem@us. ibm. com © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Session Agenda § Web Services introduction § CICS Web Services artifacts – Transports – Message handler pipeline – Web Service binding file – Resource definitions • • TCPIPSERVICE URIMAP PIPELINE WEBSERVICE – Summary 5 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 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 – – 7 Message formats Transport protocols and location Independent of hardware or software platform Independent of programming language © 2005 IBM Corporation
CICS Transaction Server V 3. 1 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 – Service Bind Requester Service Provider Find Publish Service Registry Invokes the service using the WSDL – Service Registry • • 9 Hosts the service description Optional for statically bound requesters © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Web Services Introduction… § What does the “standardized XML message” look like? – SOAP 1. 1 or 1. 2 message • Soap envelope <Envelope> consisting of: – – – > 11 Optional header element, <Header> Body element, <Body> Optional fault element <Fault>, May be added by service provider © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Web Services Introduction… § An example of a SOAP message 13 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Web Services Introduction… § CICS as a Service Provider CICS Transaction Server Web Services Requester 15 CICS Web Services <XML SOAP message> COMMAREA or Channel CICS Application Program © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Web Services Introduction… § CICS as a Service Requester CICS Transaction Server CICS Application Program 17 COMMAREA or Channel CICS Web Services <XML SOAP message> Web Services Requester © 2005 IBM Corporation
CICS Transaction Server V 3. 1 CICS Web Services § CICS provides a number of artifacts for Web Services – Resource definitions • Transport definitions – TCPIPSERVICE (HTTP) – QLOCAL (Web. Sphere 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 19 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Resources for CICS as a service provider CICS TS V 3. 1 TCPIPSERVICE SOAP message Service Requester CSOL CWXN CPIH Pipeline URIMAP matching HFS pipeline config WSDL URIMAP handlers dynamic install WSBind handlers PIPELINE dynamic install CICS provided utility handlers WEBSERVICE data mapping Business Logic Language structure 21 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Resources for CICS as a service requester CICS TS V 3. 1 User Transaction Business Logic HFS data mapping Pipeline WEBSERVICE WSBind CICS provided utility dynamic install PIPELINE Language structure WSDL handlers pipeline config handlers Service Provider SOAP message 23 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 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 25 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 TCpipservice ==> 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 GROup ==> DEscription ==> Urm ==> POrtnumber ==> 00000 STatus ==> Open PRotocol Open | Closed ==> Iiop | Http | Eci | User TRansaction ==> Backlog ==> 00001 TSqprefix ==> Ipaddress ==> SOcketclose ==> No 0 -32767 No | 0 -240000 (HHMMSS) Maxdatalen ==> 3 -536870 SECURITY SSl ==> Yes | No | Clientauth CErtificate ==> PRIvacy CIphers : Supported Notsupported | Required | Supported ==> 0504352 F 0 A 0903060102 AUthenticate ==> No No | Basic | Certificate | AUTORegister | AUTOMatic | ASserted ATtachsec ==> Verify Local | Verify DNS CONNECTION BALANCING DNsgroup ==> GRPcritical ==> No 27 1 -65535 No | Yes © 2005 IBM Corporation
CICS Transaction Server V 3. 1 CICS Web Services… § Define the input queue § WMQ definition DEFINE QLOCAL ('queuename') DESCR ('description') PROCESS(processname) INITQ('initqueue') – Target service will flow in the MQ RFH 2 header • Format is ‘/string’ • Matching occurs on URIMAP path – Default target service • Used if not specified in request TRIGGER TRIGTYPE(FIRST) TRIGDATA('default target service') BOTHRESH(nnn) BOQNAME('requeuename') 29 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 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 • 31 Userid under which the web service will execute © 2005 IBM Corporation
CICS Transaction Server V 3. 1 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 PIPELINE ==> Group ==> Description ==> Status ==> Enabled | Disabled Configfile ==> (Mixed Case) ==> ==> Shelf ==> (Mixed Case) ==> ==> Wsdir ==> (Mixed Case) ==> ==> – WSDIR • 33 Pickup directory for WS Bind files © 2005 IBM Corporation
CICS Transaction Server V 3. 1 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 • WEBSERVICE Group Description Pipeline (Mixed Case) ==> ==> WSBIND ==> (Mixed Case) ==> ==> WSDLFILE ==> (Mixed Case) ==> ==> VALIDATION ==> NO NO|YES HFS name of the WSDL file – VALIDATION • • 35 Run time SOAP message validation against WSDL schema WSDL file needs to be available for validation (YES) © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Web Service Resource Interrelationships URIMAP USAGE(PIPELINE) HOST PATH PIPELINE WEBSERVICE CICS HFS PIPELINE CONFIGFILE SHELF WSDIR dynamic install config COMMAREA structure pick-up directory WSBind WEBSERVICE PIPELINE WSBIND WSDLFILE WSDL 2 CICS BINDING= URI= PGMNAME= PGMINT= 37 WSDL © 2005 IBM Corporation
CICS Transaction Server V 3. 1 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 39 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 CICS Web Services… § Pipeline structure for a service provider Pipeline Transport Service Default HTTP Default MQ Transport Handler List Handler Service handler list handler CICS SOAP 1. 1 handler Service handler list CICS SOAP 1. 2 handler CICS SOAP 1. 1 handler CICS SOAP 1. 2 handler App. Handler Service Parameter List 41 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 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. w 3. org/2001/XMLSchema-instance" xsi: schema. Location="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> 43 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 CICS Web Services… § Pipeline structure for a service requestor Requestor Pipeline Service handler list handler Transport CICS SOAP 1. 1 handler CICS SOAP 1. 2 handler Default HTTP Default MQ Transport Handler List Handler Service Parameter List 45 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 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. w 3. org/2001/XMLSchema-instance" xsi: schema. Location="http: //www. ibm. com/software/htp/cics/pipeline/Requester. xsd "> <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> 47 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 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 • • 49 Between CICS and the message handler Between message handlers © 2005 IBM Corporation
CICS Transaction Server V 3. 1 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 – 51 e. g. pass state data © 2005 IBM Corporation
CICS Transaction Server V 3. 1 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 • 53 Conveys error information between message handlers © 2005 IBM Corporation
CICS Transaction Server V 3. 1 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 • 55 Contents of the appropriate <handler_parameter_list> for the SOAP handler © 2005 IBM Corporation
CICS Transaction Server V 3. 1 CICS Web Services… § SOAP message handlers – CICS provided message handlers to process SOAP messages • • SOAP 1. 1 and 1. 2 Input processing – • 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 – – 57 Extract the <Body> for use by your application program Examine the message and the header on input and output messages Add headers to outbound messages © 2005 IBM Corporation
CICS Transaction Server V 3. 1 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: • • 59 URI match occurs <Mandatory> true is specified © 2005 IBM Corporation
CICS Transaction Server V 3. 1 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. w 3. org/2001/XMLSchema-instance" xsi: schema. Location="http: //www. ibm. com/software/htp/cics/pipeline. . /Schema/New. 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: headerprogram> <!-- Define the program that will be executed to deal with this header --> <p: program_name>MYPROG 1</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>my. Header</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> 61 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 CICS Web Services… § SOAP node interfaces – Header handler interface • Passes information between the SOAP node and the header handler program – Application handler interface • 63 Passes information between the SOAP node and an application handler © 2005 IBM Corporation
CICS Transaction Server V 3. 1 CICS Web Services… § SOAP header processing interface – Channel DFHHHC-V 1 passed to both SOAP 1. 1 and 1. 2 nodes – Containers • DFHHEADER – • DFHWS-XMLNS – • • Body of the SOAP envelop DFHFUNCTION – 65 Information about the name space DFHWS-BODY – • Header block that caused the handler to be driven Reason the SOAP handler was invoked Any user containers created in the channel © 2005 IBM Corporation
CICS Transaction Server V 3. 1 CICS Web Services… § SOAP application handler interface – Channel DFHAHC-V 1 passed to the application handler – Containers • DFHWS-XMLNS – • DFHWS-BODY – • 67 Body of the SOAP envelope DFHNORESPONSE – • Name-value pairs that map namespace prefixes to namespaces Indication from application handler that no response is to be generated Any user containers created in the channel © 2005 IBM Corporation
CICS Transaction Server V 3. 1 CICS Web Services… § Programming Interfaces – Fault Processing • SOAP <Fault> is used to carry error information – • 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 – – – 69 Contained in the body of a message <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 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 CICS Web Services… § Programming Interfaces – Fault Processing • EXEC CICS SOAPFAULT CREATE FAULTCODE ( ) FAULTSTRING ( ) FAULTSTRLEN ( ) ROLELENGTH ( ) FAULTACTOR ( ) FAULTACTLEN ( ) DETAILLENGTH ( ) NATLANG ( ) – • EXEC CICS SOAPFAULT ADD SUBCODEST ( ) SUBCODELEN ( ) FAULTSTRING ( ) FAULTSTLEN ( ) NATLANG ( ) – • Add a reason to an existing fault in a specified language EXEC CICS SOAPFAULT DELETE – 71 Create a SOAP fault Delete a Soap Fault that has been created © 2005 IBM Corporation
CICS Transaction Server V 3. 1 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) – 73 Setting up the Channel and Container structure © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Web Services Statistics… PIPELINE Name. . : DFHWSATP PIPELINE Enable Status. . : Disabled Configuration file. . . : /usr/lpp/cicsts/pipeline/configs/registrationservice. PROV. 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/registrationservice. REQ. xml Shelf directory. . . . : / var/cicsts/ WSDIR pickup directory. . : PIPELINE use count. . . : 75 0 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 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/dbeard 1/wsbind/CPYBEARD Web service WSDL binding. . . : Endpoint. . . : Validation. . . : Yes Program interface. . . . : Program name. . . : Container. . . : WEBSERVICE use count. . . . : 77 0 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 CICS Web Services Monitoring § New field WBIWSSCT – Number of INVOKE WEBSERVICE requests for this task – Added to monitoring group DFHWEBB 79 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 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) 81 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 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 83 © 2005 IBM Corporation
- Slides: 41