Understanding Urimaps, Pipelines and Webservices For CICS100407
Understanding Urimaps, Pipelines and Webservices For CICS100407
Understanding Urimaps, Pipelines and Webservices For CICS100407
Agenda:
Web service overview
Requester / Provider, SOAP, WSDL, WSBIND
SOAP example
<SOAP-ENV:Body> <dispatchOrderRequest xmlns= "http://www.exampleApp.dispatchOrder.Request.com"> <itemReferenceNumber>10</itemReferenceNumber> <quantityRequired>5</quantityRequired> <customerId>STEVEW </customerId> <chargeDepartment>PLANNING</chargeDepartment> </dispatchOrderRequest> </SOAP-ENV:Body>
WSDL
XML document detailing specifications needed to invoke Web service Platform and programming language independent
WSDL - notes
WSDL can be exchanged between application programmers within an organization to implement a requester and provider application. WSDL can also be exchanged between companies that wish to communicate through Web services. WSDL is not tied to a particular programming language or operating system platform so it enables different applications running on different platforms to communicate according to the specifications of the WSDL document.
10
WSDL example
dispatchOrder itemReferenceNumber: <xsd:element name="itemReferenceNumber" nillable="false"> <xsd:simpleType> <xsd:restriction base="xsd:short"> <xsd:maxInclusive value="9999" /> <xsd:minInclusive value="0" /> </xsd:restriction> </xsd:simpleType> </xsd:element>
11
12
13
14
15
16
WSDL Equivalent
<xsd:element name="itemReferenceNumber" nillable="false"> <xsd:simpleType> <xsd:restriction base="xsd:short"> <xsd:maxInclusive value="9999" /> <xsd:minInclusive value="0" /> </xsd:restriction> </xsd:simpleType> </xsd:element>
17
18
19
20
Binding WSBIND
Connects WSDL and data structure Enables inbound SOAP message mapping to data structure Enables data structure mapping to outbound SOAP message WSBIND must match WSDL and data structure being used
21
22
Pipeline Structure
Message handler is a program that can process Web service requests and responses Message handler can modify request / response Pipeline consists of series of message handlers executed in a sequence May have different message handlers for HTTP vs MQ transports
23
24
Message Handler 3
25
26
27
28
Data Mapper
Request Service Requester Response Message Handler 1 CICS Web Services Message Handler 2
WSBIND WSDL
Message Handler 3
29
30
Business Logic
Client Communications Logic
CICS Transaction Server
EXEC CICS LINK
Business Logic
Client
Business Logic
31
32
33
34
Wrapper Program
If tooling cannot generate code to interact directly with business logic Create data structure for wrapper Manipulate data for business logic program Moves data between wrappers data structure and business logics data structure Invokes business logic program
35
36
Wrapper Program
CICS Transaction Server
Business Logic
37
38
39
TCPIPSERVICE
Required for service provider using HTTP Provides access to CICS from TCP/IP network via port number
40
TCPIPSERVICE - notes
There are other parameters on the TCPIPSERVICE definition, but for this presentation, PORT is the important one. The CICS Catalog manager sample application uses a TCPIPSERVICE name of EXMPPORT and I used Port 08021. Tcpipservice(EXMPPORT) Port(08021)
41
URIMAP
Required for service provider Passes incoming request to appropriate pipeline based on URI (URL) match on the PATH attribute Usually created automatically from WSBIND when pipeline is installed
42
URIMAP - notes
For example, the following attributes of interest are for the URIMAP automatically created for the CICS catalog sample application after installing Pipeline(EXPIPE01). Urimap($918180) Usage(Pipe) Pipe indicates this for an inbound request, where CICS will be the provider of the information.
43
44
45
46
PIPELINE
Required in both provider and requester Pipeline configuration file z/OS UNIX XML file details of message handler programs Location of WSDL and WSBIND files URIMAP name WEBSERVICE name
47
PIPELINE - notes
CICS provides a standard set of message handlers that you can use to enable different options in your pipeline. A basic pipeline sample, basicsoap11provider.xml, is provided in library /usr/lpp/cicsts/samples/pipelines The PIPELINE definition EXPIPE01, for the CICS catalog manager sample application, would look like the following from a CEMT INQUIRE PIPELINE - depending on the location of your configfile, pickup directory etc: Pipeline(EXPIPE01) Mode(Provider) Soaplevel(1.1)
48
49
50
WEBSERVICE
Required if CICS Web services assistant was used Usually created automatically from WSBIND when pipeline is installed PROGRAM attribute required for service provider PROGRAM can not be specified for service requester
51
WEBSERVICE - notes
The CICS catalog manager sample application WEBSERVICE definition dispatchOrderEndpoint (installed automatically from the Wsdir pickup directory when the PIPELINE is installed) would look like the following from a CEMT INQUIRE WEBSERVICE. I have only included attributes of interest to this presentation. Webservice(dispatchOrderEndpoint) Pipeline(EXPIPE01) Pipeline associated with this Webservice
52
WEBSERVICE - notes
Urimap($918180) Urimap associated with this Webservice. It was installed automatically when the pipeline was installed. Program(DFH0XODE) Name of program that implements the Webservice. DFH0XODE is a CICS supplied COBOL program that performs the Order Dispatch function. Pgminterface(Commarea) The program expects input in the form of a commarea (this could also be a channel)
53
WEBSERVICE - notes
Wsbind(/u/webbste/dir1/spud20/dir2/samples/webservices/wsbind/pr ovider/dispatchOrderEndpoint.wsbind) Webservice binding file used to convert data structure to WSDL and WSDL to data structure. Endpoint(http://my-server:9080/exampleApp/dispatchOrder) Endpoint URI of a remote Webservice, specified in the WSDL, and it is picked up from the WSBIND file in the WSDIR pickup directory. Binding(dispatchOrderSoapBinding) From WSDL file - <binding name="dispatchOrderSoapBinding" type="tns:dispatchOrderPort"> It is picked up from the WSBIND file in the WSDIR pickup directory.
54
WEBSERVICE - notes
A WEBSERVICE is required if you use the CICS tooling since it specifies the location of the resources necessary for CICS to convert the SOAP message to a data structure (and data structure to SOAP message). If the CICS tooling is not used, the message handlers in your pipeline would need to communicate with the business logic directly and do the translation from SOAP message to data structure and from a data structure to a SOAP message.
55
PIPELINE Configuration
<?xml version="1.0" encoding="EBCDIC-CP-US"?> <provider_pipeline xmlns="http://www.ibm.com/software/htp/cics/pipeline" xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance" xsi:schemaLocation="http://www.ibm.com/software/htp/ cics/pipeline provider.xsd "> <service> <terminal_handler> <cics_soap_1.1_handler/> </terminal_handler> </service> <apphandler>DFHPITP</apphandler> </provider_pipeline>
56
57
58
Install Pipeline
Creates WEBSERVICE and URIMAP definitions based on WSBIND information from WSDIR pickup directory Install done in two stages Resource Definition Online (RDO) phase Pipeline resolution phase
59
60
61
62
63
64
65
66
HIGHLY Recommended
67
68
Debugging
CEDF / CEDX AUXTRACE Dump with trace components Validation Editor for validating WSDL document Log file and job output from tooling Reporting problems to IBM
http://www-306.ibm.com/software/htp/cics/tserver/support/ MustGather: Documentation for Web services problems in CICS on z/OS
69
Debugging - notes
CEDX can be used to step through Web services processing. Trace is a very valuable tool for debugging runtime problems with a URIMAP, PIPELINE or WEBSERVICE. Typically I would recommend all standard trace components set to level 1, and the following set to standard level 1-2: AP, EI, PI, PG, SO and WB. If you are receiving a CICS message, you can set up the trace components as above, with an appropriate internal trace table size (10-20 Meg is usually good), and obtain a dump on the CICS message by putting it into the system dump table. For example, if you were getting a DFHPI1234, you can put this in the system dump table with: CEMT SET SYD(PI1234) SYS MAX(1) ADD
70
Debugging - notes
Turning on validation for the WEBSERVICE will help find problems in the message exchange process between a requester and a provider. CEMT SET WEBSERVICE(name) VALIDATION can be used, or specify it on the RDO definition of the WEBSERVICE if it is RDO defined. The validation status can be changed with CEMT. Using a WSDL editor that can perform validation can help find problems with a WSDL file before you try to run it through the CICS Web services assistant. If the WSDL isnt valid, DFHWS2LS will not be able to process it. If it passes a WSDL editors validation tests, it doesnt necessarily mean DFHWS2LS will be able to process it. But if it fails the WSDL editors validation, then the WSDL needs to be fixed before trying to process it with DFHWS2LS. Examine the log file produced by the CICS Web services assistant as well as the job output from DFHWS2LS and DFHLS2WS.
71
Summary
Web service components CICS Web services assistant tooling (and WD/z) Application considerations CICS Web services resources CICS Catalog manager sample application Debugging
72
References
CICS Transaction Server for z/OS Web Services Guide SC34-6838 CICS Transaction Server for z/OS Resource Definition Guide SC34-6815 IBM Redbooks http://www.redbooks.ibm.com/ Search: CICS Web services CICS SOA
73
74
75