CICS Transaction Server V 3 1 HTTP Support
- Slides: 79
CICS Transaction Server V 3. 1 HTTP Support Upgrade Takahiro Ishiwatari ishwtari@jp. ibm. com © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Acknowledgements § The following are trademarks of International Business Machines Corporation in the United States, other countries, or both: IBM, CICS/ESA, CICS TS, CICS Transaction Server, DB 2, MQSeries, OS/390, Web. Sphere, z/OS, z. Series, 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 NT, 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. 3 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Agenda § HTTP fundamentals § New features in CICS TS V 3. 1 • HTTP 1. 1 compliance • HTTP processing in CICS – CICS as an HTTP server – CICS as an HTTP client • Code conversion • Other changes 5 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 HTTP fundamentals § URI and URL § HTTP request and response § CICS Web Support processing in CICS TS V 2 Information for HTTP specifications can be found at § HTTP/1. 0 RFC 1945 ( http: //www. w 3. org/Protocols/rfc 1945 ) § HTTP/1. 1 RFC 2616 (http: //www. w 3. org/Protocols/rfc 2616 ) 7 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 URI and URL § URL (Uniform Resource Locator) • identifies a resource available on the internet – format specified in RFC 1738 (http: //www. ietf. org/rfc 1738. txt) § URI (Uniform Resource Identifier) • identifies an abstract or physical resource – format specified in RFC 2396 (http: //www. ietf. org/rfc 2396. txt) • URL is a subset of URI – URL is a representation of a primary access mechanism (a network location) • another form of URI is URN (Uniform Resource Name) URI http: news: ftp: urn: oasis: telnet: isbn: URN URL 9 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 URI and URL § Components of URI and URL • scheme – such as http, https • scheme specific part – an HTTP scheme will have > host > port > path > query-string scheme host port path query-string http : / / www. ibm. com : 80 / Scripts / Global / nph-cc ? cc=at 11 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 HTTP request and response § HTTP request contains • request line – method > GET, POST, HEAD, etc. – document path > /Scripts/Global/npb-cc? cc=at – HTTP version number > HTTP/1. 0, HTTP/1. 1 • (optional) header section – HTTP headers > Host, Content-type, etc. – ends with a blank line • (optional) entity body – user data > e. g. name value pairs 13 request line POST /Scripts/Global/nph-cc? cc=at HTTP/1. 1 Accept: image/gif, image/jpeg, */* User-Agent: Mozilla/4. 0 (compatible; MSIE 6. 0, Windows NT 5. 0) Host: www. sample. ibm. com: 80 Content-type: text/plain; charset=ISO-8859 -1 header section Content-length: 80 (blank line) aa=zzzzz&bb=yyyyy&cc=xxxxxx. . . entity body © 2005 IBM Corporation
CICS Transaction Server V 3. 1 HTTP request and response § HTTP response contains • response line – HTTP version number > HTTP/1. 0, HTTP/1. 1 – status code > 200, 404, 500, etc. – text describing the status code • (optional) header section – HTTP headers > Connection, Content-type, etc – ends with a blank line • (optional) entity body – user data > e. g. HTML document 15 HTTP/1. 1 200 OK Date: Fri, 13 Aug 2004 19: 02: 57 GMT Connection: close Content-Type: text/html; charset=ISO-8859 -1 Content-length: 00003255 (blank line) <HTML> <HEAD>…</HEAD> <BODY>…</BODY> </HTML> response line header section entity body © 2005 IBM Corporation
CICS Transaction Server V 3. 1 CICS Web Support processing in CICS TS V 2 § Inbound HTTP requests • Can invoke COMMAREA based applications or 3270 transactions • APIs supplied for web aware programs > EXEC CICS WEB API, EXEC CICS DOCUMENT API • Supports HTTP/1. 0 > non-HTTP requests can also be processed Socket Web Attach Listener transaction (CSOL) （CWXN） DFHCCNV (Header) Analyzer DFHCCNV (User Data) Alias Business transaction Logic (CWBA) CICS Converter (Decode) Application or 3270 transaction via DFHWBTTA Interface (DFHWBBLI) Converter (Encode) DFHCCNV 17 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 CICS Web Support processing in CICS TS V 2… § example URL for the supplied analyzer • for commarea applications http: //hostname: 80/CNV 1/CWBA/USRPGM 1 Converter program Alias tranid Target program • for 3270 applications http: //hostname: 80/CICS/CWBA/DFHWBTTA/AMNU Converter program Alias tranid Web Bridge program Target tranid § HTTP requests can be processed via Web server • Web server will invoke the Business Logic Interface (DFHWBBLI) via EXCI 19 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 CICS Web Support processing in CICS TS V 2… § Outbound HTTP requests • Linkable interface provided in CICS TS V 2. 2 and above – EXEC CICS LINK PROGRAM(DFHWBCLI) – All information and data specified in COMMAREA > Functions: Inquire proxy, Send, Receive, Converse, Close > target URL information > pointer to header area and body area > response and reason codes – Used in SOAP for CICS feature CICS 21 LINK for Send DFHWBCLI LINK for Receive DFHWBCLI LINK for Close DFHWBCLI HTTP request HTTP response © 2005 IBM Corporation
CICS Transaction Server V 3. 1 What’s new in CICS TS V 3. 1 § HTTP/1. 1 compliance § HTTP processing in CICS • CICS as an HTTP server – URIMAP resource definition • CICS as an HTTP client – EXEC CICS commands for outbound support § Code page conversion § Other changes 23 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 HTTP/1. 1 compliance § CICS is conditionally compliant with HTTP/1. 1 specification • ‘Conditionally compliant’ means… – for the requirements that are relevant to the functions provided by CICS, > CICS satisfies all the MUST level requirements > but not all the SHOULD level requirements • responsibility for compliance – User applications also share responsibility > may fail to meet the SHOULD requirements, depending on actions performed by the application > CICS provides facilities and documentation to help make applications compliant with HTTP/1. 1 25 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 HTTP/1. 1 compliance… § New features that CICS provides for HTTP/1. 1 compliance • • • 27 Supported methods HTTP date and time formats Persistent connections Pipelining Chunking © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Supported Methods § Methods supported • For HTTP/1. 0 in CICS – GET, HEAD, POST, PUT, DELETE, LINK, UNLINK, REQUEUE > RFC 1945(HTTP/1. 0) lists GET, HEAD, POST as supported methods • For HTTP/1. 1 – GET, HEAD, POST, PUT, DELETE, OPTIONS, TRACE > LINK, UNLINK, REQUEUE methods are not supported – CICS actions for status codes also made compliant § Message body handling • should be no body for GET, HEAD, DELETE, TRACE methods – ignore on input – INVREQ on output 29 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Supported Methods and CICS handling Method GET PUT POST HEAD received from 1. 0 Client received from 1. 1 Client Ignore Message body Pass to application Ignore Message body send to 1. 0 server sent to server Invreq if body present to server with body sent to server with body Invreq if no body present sent to server Invreq if body present LINK Pass to application 501 – not implemented Invreq UNLINK Pass to application 501 – not implemented Invreq REQUEUE Pass to application 501 – not implemented Invreq DELETE Pass to application sent to server OPTIONS 501 – not implemented Handle all in CWXN Invreq sent to server 501 if not OPTIONS * 31 send to 1. 1 server Invreq if not OPTIONS * TRACE 501 – not implemented Handle all in CWXN Invreq sent to server CONNECT 501 – not implemented Invreq © 2005 IBM Corporation
CICS Transaction Server V 3. 1 HTTP date and time stamp formats § Date and time stamps used in HTTP headers • HTTP/1. 1 clients and servers must accept – Tue, 01 Apr 2003 10: 01: 02 GMT – Tuesday, 01 -Apr-03 10: 01: 02 GMT – Tue Apr 01 10: 01: 02 GMT • only generate the RFC 1123 format – Tue, 01 Apr 2003 10: 01: 02 GMT : RFC 1123 format : RFC 1036 format : ANSI C’s asctime() format : RFC 1123 format § Uses of HTTP date and time stamps in CICS • On receive, – Applications can read the HTTP headers and convert the time into absolute time • On send, – CICS will automatically produce the Date header in the required format – For other HTTP headers that need date & time stamps, application needs to convert absolute time (ABSTIME) to RFC 1123 format 33 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 HTTP date and time stamp formats… § CICS will supply APIs to handle conversion – EXEC CICS CONVERTTIME • converts HTTP formats to ABSTIME EXEC CICS CONVERTTIME DATESTRING (‘Tue, 01 Apr 2003 10: 01: 02 GMT’) ABSTIME (+003258180062000) – EXEC CICS FORMATTIME • converts ABSTIME to HTTP format • new options DATESTRING and STRINGFORMAT – STRINGFORMAT specifies the type of format in cvda – currently only 646 (RFC 1123) is supported > if DATESTRING present and STRINGFORMAT not specified, RFC 1123 is used EXEC CICS FORMATTIME ABSTIME (+003258180062000) STRINGFORMAT (RFC 1123) DATESTRING (‘Tue, 01 Apr 2003 10: 01: 02 GMT’) 35 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Persistent connections § In previous CICS releases • Compliant with HTTP/1. 0 – by default, CICS would close the connection when data received – Web client would send “Connection: Keep-Alive” header to keep connection open • Can be ultimately controlled by SOCKETCLOSE on TCPIPSERVICE – normally would specify SOCKETCLOSE(0) unless SSL • CWXN will remain in system until socket closed – System may get flooded with inactive CWXN tasks CWXN CWBA socket connection 37 Socketclose CICS © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Persistent connections… § In CICS TS V 3. 1 • Compliant with HTTP/1. 1 persistent connection – CICS will keep the session open by default – Session closed when requested (e. g. in header, client termination, timeout, etc. ) – SOCKETCLOSE(0) will fail to meet the requirements for HTTP/1. 1 • Asynchronous sockets support for CWXN – CWXN terminates but socket still open (“pseudo conversational”) – Eliminates CWXN tasks suspending in the system CWXN socket connection 39 CWBA CWXN CWBA Socketclose CICS © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Pipelining § Send multiple request without waiting for response • responses are returned in the same sequence that the request was received • requests should be idempotent – i. e. same result is always obtained when the requests are repeated • requires persistent connection SEND RECEIVE Client 41 request A request B request C request D response A response B response C response D RECEIVE SEND Server © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Pipelining… § CICS support for pipelining • CICS acting as a server – CICS will process the requests serially as separate transactions – remaining requests in the pipelined message will be held until the response is sent SEND RECEIVE request A request B request C RECEIVE SEND response A response B response C RECEIVE SEND • CICS acting as a client – Application will connect to a remote server and issue a series of send requests > each request is sent immediately – Application should receive the pipelined responses in the order the request was sent 43 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Chunking § Chunked transfer-coding • transfer data in convenient segments – dynamically produced contents – large amount of content • Sends the body of a message in chunks – each chunk has its own size indicator – may be followed by optional trailer headers – end-of-message is indicated by a chunk with zero length and an empty line > empty line signified by <CRLF> • recipient will receive the message as a whole – recipient can verify that it received the complete message 45 … … SEND RECEIVE © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Chunking… § CICS support for chunking • On inbound, – wait until all the chunks are received – application can receive the data with a single WEB RECEIVE command – If CICS is acting as a server, > timeout value set by SOCKETCLOSE in TCPIPSERVICE > total amount of data is limited by the MAXDATALEN attribute in TCPIPSERVICE – If CICS is acting as a client > RTIMOUT value for the executing transaction applied • On outbound, – Application specifies chunking by CHUNKING（CHUNKYES) on each WEB SEND command > CICS will create the “Transfer-Encoding: chunked” and “chunk-size” header > CICS DOCTEMPLATEs cannot be used directly in chunking – to end chunking, send a CHUNKING(CHUNKEND) 47 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 TCPIPSERVICE change § PROTOCOL ( ECI | HTTP | IIOP | USER ) • HTTP 1. 1 states an error response to be returned for non-HTTP methods – previously customers will default to PROTOCOL(HTTP) for request other than HTTP, ECI, IIOP and use CICS Web Support to handle the request. – non-HTTP request on a PROTOCOL(HTTP) port will return 501 error • New USER option – used for non-HTTP methods – CICS Web Support will still be invoked but under a different tranid. > CWXU - but same program used as CWXN > non-HTTP processing is exactly the same as today. - no code conversion prior to analyzer - Invokes the converter program if required - Invokes the target application – may need to change port for migration 49 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 TCPIPSERVICE change … § MAXDATALEN ( 32 KB | number KB ) • Maximum data that can be received on the port for the service – limit amount of data received by chunking – to prevent denial of service • minimum of 32 KB (default) – maximum is 0. 5 GB § SOCKETCLOSE • Recommendation change – Formerly, SOCKETCLOSE(0) was recommended – In CICS TS V 3. 1, recommendation is to not specify SOCKETCLOSE(0) > SOCKETCLOSE(0) will fail to meet the requirements for HTTP/1. 1 51 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 HTTP processing in CICS § CICS as an HTTP server • Web client sends an HTTP request to CICS HTTP request CICS Web HTTP response Support CICS Application § CICS as an HTTP client • CICS sends an HTTP request to a remote server HTTP request CICS Application Outbound HTTP Support 53 HTTP response © 2005 IBM Corporation
CICS Transaction Server V 3. 1 CICS as an HTTP server § Processing changes in CICS TS V 3. 1 • New URIMAP resource to determine the processing for the request – Types of processing > Redirection > Static response > Application response • API changes – WEB API changes > Support for chunking – HTTP date and time stamp format handling > CONVERTTIME, FORMATTIME • Code conversion changes – Support for UTF-8, UTF-16 code page conversions 55 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 URIMAP for CICS as an HTTP server § A URIMAP will • match the incoming URI and… – invoke a CICS application, or > directly > using analyzer and converter programs – supply a static response, or > specify code conversion characteristics – redirect HTTP requests to a specified URL, or – invoke a CICS Web service • Analyzer is invoked if no URIMAP matches scheme host port path query-string http : / / www. ibm. com : 80 / Scripts / Global / nph-cc ? cc=at 57 URIMAP definition URIMAP ==> SAMPURI USAGE ==> Server Universal Resource Identifier SCHEME ==> HTTP HOST ==> www. ibm. com PATH ==> Scripts/Global/* Associated CICS resource …. Static Document Properties …. Redirection …. © 2005 IBM Corporation
CICS Transaction Server V 3. 1 CICS Web Support processing in CICS TS V 3. 1 § New URIMAP resource to determine the processing for the request • analyzer programs are now optional • more flexible URI path – remove CICS specific resource names from path CICS Socket Web Attach Listener transaction (CSOL) (CWXN) DFHCCNV (Header) URIMAP matching Analyzer DFHCCNV (User Data) Alias Business transaction Logic (CWBA) Interface (DFHWBBLI) Converter (Decode) Application or 3270 transaction via DFHWBTTA Converter (Encode) DFHCCNV 59 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Application response § An application program is executed to service the request • program can be specified by – PROGRAM attribute in URIMAP definition – Analyzer program – Converter program • program can be – “Web-aware” using EXEC CICS WEB and DOCUMENT APIs – COMMAREA program – 3270 application HTTP request CICS Web HTTP response 61 CICS Application Support © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Application response… § URIMAP for Web aware programs • essentially, you only need to specify PROGRAM attribute – let the other parameters default • if you want to use an analyzer program – specify ANALYZER(YES) and TCPIPSERVICE > analyzer program on TCPIPSERVICE will be used – the following may be overridden by analyzer > CONVERTER, TRANSACTION, USERID, PROGRAM – if ANALYZER(NO) > CONVERTER or PROGRAM or both must be present • if you want to use a converter program – specify CONVERTER – PROGRAM may be overridden by converter • optionally specify. . – TRANSACTION > default is CWBA, always run DFHWBA program – USERID > may be overridden by AUTHENTICATE in TCPIPSERVICE 63 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Application response… § URIMAP for COMMAREA applications • Specify the target program in PROGRAM attribute • Specify CONVERTER to do the decode and encode functions – if not specified by analyzer program § URIMAP for 3270 applications • Specify Web Terminal Translation Application in PROGRAM attribute – DFHWBTTA, DFHWBTTB or DFHWBTTC • PATH should be generic – e. g. /terminal/* • Format for the rest of the path – /[transaction name]+[input parameters]? [token] > e. g. /cemt+inq+task 65 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Static response § Responses without the need to invoke an application program • from a CICS DOCTEMPLATE resource or a file on HFS – HFS file can also be specified in DOCTEMPLATE • if DOCTEMPLATE – can use query strings to substitute symbols > query string must not be included in the PATH attribute of URIMAP – passes the content as a symbol string HTTP request CICS Web HTTP response doc template Support HFS 67 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Static response… § In URIMAP definition • specify the location of the document – TEMPLATENAME used for CICS DOCTEMPLATEs – HFSFILE used for HFS files • path matching can be used – wild card character specified in the PATH, and TEMPLATENAME / HFSFILE /findout/pictures/bluefish. jpg PATH ==> findout/pictures/* HFSFILE ==> /u/facts/image/* /u/facts/image/bluefish. jpg • specify MEDIATYPE – i. e. text/html, text/xml, etc. • if text type document specify – CHARACTERSET: default is ISO-8859 -1 – HOSTCODEPAGE: default is LOCALCCSID on SIT • ANALYZER(NO) is required 69 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Redirection § Redirect to another location on the web • permanently or temporarily • can be changed by SET URIMAP command for redirection HTTP request CICS CWS 301/302 response Redirected HTTP request § In URIMAP definition • specify LOCATION attribute – with REDIRECTTYPE( NONE | TEMPORARY | PERMANENT ) • the following will be inactivated by setting redirection – ANALYZER, CONVERTER, HFSFILE, PIPELINE, PROGRAM, TEMPLATENAME, TRANSACTION, USERID – can reactivate by setting REDIRECTTYPE(NONE) 71 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 URIMAP definition Urimap ==> Group ==> DEscription ==> STatus ==> Enabled USAge ==> Server UNIVERSAL RESOURCE IDENTIFIER SCheme ==> HTTP HOST ==> (Mixed Case) ==> PAth ==> (Mixed Case) ==> ==> ASSOCIATED CICS RESOURCES TCpipservice ==> Analyzer ==> No COnverter ==> TRansaction ==> PRogram ==> PIpeline ==> Webservice ==> 73 Enabled | Disabled Server | Client | Pipeline HTTP | HTTPS No | Yes (Mixed Case) © 2005 IBM Corporation
CICS Transaction Server V 3. 1 URIMAP definition… 74 § STATUS({ENABLED| DISABLED}) For all USAGE options. Specifies whether the URIMAP definition is to be installed in an enabled or disabled state. § USAGE({SERVER| CLIENT| PIPELINE}) Specifies whether this URIMAP definition is for CICS as an HTTP server (SERVER), CICS as an HTTP client (CLIENT), or an XML service (PIPELINE). The USAGE attribute governs which other attributes in the URIMAP definition can be used § SCHEME({HTTP| HTTPS}) For all USAGE options. Specifies the scheme component of the URI to which the URIMAP definition applies, which is either HTTP (HTTP without SSL) or HTTPS (HTTP with SSL). § HOST(hostname) For all USAGE options. Specifies the host component of the URI to which the URIMAP definition applies, which can be up to 116 characters. An example of a host name is www. research. ibm. com. § PATH(path) For all USAGE options. Specifies the path component of the URI to which the URIMAP definition applies, which can be up to 255 characters. An example of a path is software/htp/cics/index. html. § TCPIPSERVICE(data-area) For USAGE(SERVER) and USAGE(PIPELINE). Specifies the 1 - to 8 -character name of a TCPIPSERVICE resource definition that defines an inbound port to which this URIMAP definition relates. § ANALYZER For USAGE(SERVER), where an application-determined response is to be provided. Specifies whether an analyzer program is to be used in processing the HTTP request from the Web client. § CONVERTER(data-area) For USAGE(SERVER), where an application-determined response is to be provided. Specifies the 1 -8 character name of a converter program that is to be run to perform conversion or other processing on the content of the request. § TRANSACTION(data-area) For USAGE(SERVER), where an application-determined response is to be provided and USAGE(PIPELINE). 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 HTTP request from the Web client § PROGRAM(data-area) For USAGE(SERVER), where an application-determined response is to be provided. Specifies the 1 -8 character name of the user application program that composes a response to the HTTP request from the Web client. § PIPELINE(data-area) For USAGE(PIPELINE). Specifies the 1 -8 character name of the Pipeline Resource definition that defines the application that processes the request. § WEBSERVICE(data-area) For USAGE(PIPELINE). Specifies the name of the Web Service Resource definition that defines the application that processes the request. © 2005 IBM Corporation
CICS Transaction Server V 3. 1 URIMAP definition (continued) SECURITY ATTRIBUTES USErid ==> CIphers ==> CErtificate ==> STATIC DOCUMENT PROPERTIES Mediatype ==> CHaracterset ==> HOSTCodepage ==> TEmplatename ==> HFsfile ==> (Mixed Case) ==> ==> REDIRECTION Redirecttype ==> None Location ==> (Mixed Case) ==> ==> ==> 75 (Mixed Case) None | Temporary | Permanent © 2005 IBM Corporation
CICS Transaction Server V 3. 1 URIMAP definition (continued)… 76 § USERID(data-area) For USAGE(SERVER), where an application-determined response is to be provided, and USAGE(PIPELINE). Specifies the 1 -8 character user ID under which the alias transaction will be attached. § CIPHERS=value For USAGE(SERVER). The CIPHERS list is only used when the sockets connection established for the resource uses SSL or TLS. § CERTIFICATE(data-area) For USAGE(CLIENT). Specifies the label of the X. 509 certificate that is to be used as the SSL client certificate during the SSL handshake. § MEDIATYPE(name) For USAGE(SERVER) , where a static response is to be provided. Specifies the data content of the response that CICS provides to the HTTP request from the Web client, for example image/jpg, text/html or text/xml. Up to 40 characters can be used. § CHARACTERSET(data-area) For USAGE(SERVER) , where a static response is to be provided. Specifies the 1 -40 character name of the character set into which CICS converts the entity body of the response that is sent to the Web client. ISO-8859 -1, the default character set for the Web, is used as the default if this attribute is not specified. § HOSTCODEPAGE(data-area) For USAGE(SERVER) , where a static response is to be provided. Specifies the 1 -10 character name of the IBM code page (EBCDIC) that is used in the CICS system when handling this request. This attribute only applies where a text document is used to provide a response to the request, or where the request includes an entity body in a text format. § TEMPLATENAME(data-area) For USAGE(SERVER), where a static response is to be provided. Specifies the 1 -48 character name of a CICS document template that will form the static response which is sent to the HTTP request from the Web client. § HFSFILE(data-area) For USAGE(SERVER), where a static response is to be provided. Specifies the fully qualified name of a UNIX System Services HFS file that will form the static response which is sent to the HTTP request from the Web client. § REDIRECTTYPE(NONE|TEMPORARY|PERMANENT) For USAGE(SERVER) and USAGE(PIPELINE). Specifies the type of redirection for requests that match this URIMAP definition. The URL specified by the LOCATION attribute is used for redirection when required. § LOCATION(data-area) For USAGE(SERVER) and USAGE(PIPELINE). Specifies a URI of up to 255 characters to which the HTTP request should be redirected. © 2005 IBM Corporation
CICS Transaction Server V 3. 1 URIMAP valid attributes USAGE(SERVER) USAGE(CLIENT) USAGE(PIPELINE) STATUS ENABLED / DISABLED SCHEME HTTP / HTTPS HOST required PATH required TCPIPSERVICE optional n/a optional ANALYZER YES / NO n/a CONVERTER optional n/a TRANSACTION optional n/a optional PROGRAM optional n/a PIPELINE n/a required WEBSERVICE n/a required optional n/a optional CIPHERS n/a optional n/a CERTIFICATE n/a optional n/a MEDIATYPE optional n/a CHARACTERSET optional n/a HOSTCODEPAGE optional n/a TEMPLATENAME optional n/a HFSFILE optional n/a REDIRECTTYPE optional n/a optional LOCATION optional n/a optional USERID 77 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Managing URIMAP resource § URIMAP resource • Can be managed via CEMT or SPI commands • INQUIRE URIMAP – Inquire on the current URIMAP settings • SET URIMAP – Enable or disable the status > when disabled, HTTP requests will get a 503 (Service Unavailable) – Temporarily redirect to a remote server 79 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Virtual hosting § Having multiple host names for the same IP address • DNS host name resolution returns same IP address for different host names • HTTP/1. 1 specification allows the host name to be stored in a “Host” header – In HTTP/1. 0, host name was lost after resolution • Can treat requests with different host names as different resources http: //www-1. ibm. com DNS resolution http: //www-2. ibm. com DNS server http: //204. 146. 81. 99 DNS resolution http: //204. 146. 81. 99 GET /htp/cics/index. html HTTP/1. 1 Host: www-1. ibm. com Host: www-2. ibm. com 204. 146. 81. 99 81 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Virtual hosting… § CICS will form a group of virtual hosts from URIMAP definition • HTTP requests are mapped to the virtual host • virtual hosts can be managed by INQUIRE and SET commands – to inquire the host name and status of the virtual host – enable or disable the status of the virtual host > when disabled, CICS will return an HTTP 503 response to the Web client host name used CICS URIMAP 1 www-1. ibm. com URIMAP 2 URIMAP 3 www-2. ibm. com TCP/IP PORT URIMAP 4 Host: www-2. ibm. com En 83 En ed URIMAP 5 URIMAP 6 URIMAP 7 URIMAP 8 ed l ab www-3. ibm. com www-4. ibm. com Host: www-1. ibm. com Host: www-4. ibm. com En ed le Host: www-3. ibm. com b sa d Di l ab © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Managing HTTP requests § Accepting or rejecting HTTP requests • Requests can be managed in different levels – On a specific URI level > SET URIMAP ENABLE/DISABLE – On a particular (virtual) host name level > SET HOST ENABLE/DISABLE – On a port level > SET TCPIPSERVICE OPEN/CLOSE – On a region level > SET TCPIP OPEN/CLOSE 85 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Receiving an HTTP request § EXEC CICS WEB RECEIVE • MAXLENGTH to specify the amount passed to the application • NOTRUNCATE option used for data exceeding MAXLENGTH – with NOTRUNCATE > remaining data retained and LENGERR raised > original data length is returned in LENGTH > must issue subsequent WEB RECEIVE to receive data – without NOTRUNCATE > data truncated and LENGERR raised • when the receiving data is chunked – same rule applies with MAXLENGTH and NOTRUNCATE – applies to the total length of the chunked message • to specify conversion of the entity body – SERVERCONV(SRVCONVERT) – Optionally, CHARACTERSET and HOSTCODEPAGE 87 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Sending an HTTP response § EXEC CICS WEB SEND • STATUSCODE – specify an HTTP status code to be inserted for the response • STATUSTEXT, STATUSLENGTH – specify a text to describe the reason for the status code • ACTION option – ACTION(IMMEDIATE); send a response immediately – ACTION(EVENTUAL); send a response at end of task (default) • to specify conversion of the entity body – SERVERCONV(SRVCONVERT) – Optionally, CHARACTERSET and HOSTCODEPAGE 89 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Sending an HTTP response… § EXEC CICS WEB SEND • Chunking is specified by CHUNKING(CHUNKYES) option – Sending chunked responses are always IMMEDIATE – CICS will create the headers for chunking > “transfer-encoding: chunked” on first send > “chunk-size” on each send – Data must be supplied by FROM option > DOCTOKEN cannot be used – To include Trailer headers for chunking > “Trailer” header must be sent with the first chunk > Headers written after the first chunk will be sent as trailer headers > Trailer headers are sent out with the final empty chunk – CHUNKING(CHUNKEND) will end the chunking > omitting CHUNKLENGTH key word will also end chunking 91 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Decision points for CICS as an HTTP server § HTTP/1. 0 or HTTP/1. 1 • or non-HTTP request § Use URIMAP to do… • Redirection / Static response / Application determined response § Will I use an analyzer? • Analyzer needs to be specified in TCPIPSERVICE § Will I use a converter? § What type of application? • • Web-aware, non Web-aware (commarea based), 3270 application Header handling, date and time stamp handling Chunking, pipelining Can a static response be used instead of application processing? § When and how will I do code conversion? § Security? 93 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 CICS as an HTTP client § Processing changes • API changes to replace the LINKable interface – New & changed WEB APIs > Support outbound requests > Support for chunking, pipelining – HTTP date and time format handling > CONVERTTIME, FORMATTIME • URIMAP resource for client processing • Code conversion changes – Support for UTF-8, UTF-16 code page conversions 95 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Sending an outbound HTTP request § Initiate connection • EXEC CICS WEB OPEN § Prepare outbound data • HTTP headers – EXEC CICS WEB WRITE HTTPHEADER • entity body – CICS DOCUMENTs may be used § Transmit HTTP request • EXEC CICS WEB SEND – or EXEC CICS WEB CONVERSE – may specify query string with QUERY option § Receive HTTP response • EXEC CICS WEB RECEIVE § Close connection EXEC CICS WEB OPEN prepare data to be sent write headers EXEC CICS WEB SEND EXEC CICS WEB RECEIVE check headers process received data prepare for second request EXEC CICS WEB CONVERSE check headers process received data EXEC CICS WEB CLOSE • EXEC CICS WEB CLOSE 97 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Using session tokens § SESSTOKEN option used to • specify the command is used in CICS as an HTTP client • identify a unique session – all commands related to the session > interactions with the remote server WEB SEND, WEB RECEIVE, WEB CONVERSE > manipulating HTTP headers WRITE HTTPHEADER, READ HTTPHEADER, Browse HTTP headers > closing the session WEB CLOSE 99 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Opening a session § EXEC CICS WEB OPEN • Opens a session to the remote server identified by – URIMAP with USAGE(CLIENT) or – HOST, HOSTLENGTH, PORT, SCHEME • Returns a session token for use in subsequent WEB commands – SESSTOKEN option – HTTPVNUM, HTTPRNUM returned from remote server > to check when writing HTTP headers or sending chunked data • Additional options – CERTIFICATE > X. 509 certificate to be used as SSL client certificate during SSL handshake > scheme must be HTTPS – CODEPAGE > EBCDIC code page to be used for this session. > Default is LOCALCCSID on SIT 101 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 URIMAP for CICS as an HTTP client § A URIMAP can be used to • specify the target URI – can avoid identifying URIs in programs > on WEB OPEN and WEB SEND commands • add security settings scheme host port path query-string http : / / www. ibm. com : 80 / Scripts / Global / nph-cc ? cc=at Can be supplied on WEB OPEN commands 103 URIMAP definition URIMAP ==> SAMPURI USAGE ==> Client Universal Resource Identifier SCHEME ==> HTTP HOST ==> www. ibm. com: 80 PATH ==> Scripts/Global/nph-cc Associated CICS resource …. Static Document Properties …. Redirection …. Can be supplied on WEB SEND commands © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Sending an HTTP request § EXEC CICS WEB SEND • SESSTOKEN is mandatory on CICS as an HTTP client – returned on a previous WEB OPEN command • HTTP method is specified on METHOD option – GET, POST, OPTIONS, HEAD, PUT, DELETE, TRACE • Path information for the remote server – PATH, PATHLENGTH or via URIMAP option – if URIMAP option is specified on the WEB OPEN command, it will be used as default • Can supply a query string – QUERYSTRING, QUERYSTRLEN – CICS will automatically add ‘? ’ at the beginning of the string if not present • to specify conversion of the entity body – CLIENTCONV(CLICONVERT) – Optionally, CHARACTERSET 105 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Sending an HTTP request… § EXEC CICS WEB SEND • Sending outbound is always immediate – ACTION(IMMEDIATE) is implied – ACTION(EXPECT) > CICS will send an “Expect” header and receive a “ 100 -Continue” response before sending the message body • Consecutive WEB SENDs will result in pipelining • Chunking specified by CHUNKING（YES) option – usage is same as chunking in CICS as an HTTP server • CLOSESTATUS(CLOSED) – Will send a “Connection: close” header to the remote server – no further new HTTP requests can be sent for the session 107 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Receiving an HTTP response § EXEC CICS WEB RECEIVE • SESSTOKEN is mandatory on CICS as an HTTP client – retuned on a previous WEB OPEN command • content type is returned in MEDIATYPE option • to specify conversion of the entity body – CLIENTCONV(CLICONVERT) • HTTP status code returned from the server – STATUSCODE > certain error codes are handled by CICS and not returned to the application – STATUSTEXT, STATUSLENGTH > text returned from the remote server to describe the status code • MAXLENGTH to specify the amount passed to the application – NOTRUNCATE option for data exceeding MAXLENGTH • When response is chunked – returns to application after all of the message is received • RTIMOUT for transaction applied 109 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Send a request and receive a response § EXEC CICS WEB CONVERSE • SESSTOKEN is mandatory on CICS as an HTTP client – retuned on a previous WEB OPEN command • • options mostly same as WEB SEND / WEB RECEIVE Pipelining and chunking not supported RTIMOUT for transaction applied Cannot use between WEB SEND and WEB RECEIVE commands – WEB CONVERSE will get a INVREQ < options for sending > ACTION CLOSEST DOCTOKEN FROM, FROMLENGTH MEDIATYPE METHOD PATH, PATHLENGTH QUERYSTRING, QUERYSTRLEN URIMAP 111 < options for receiving > INTO TOLENGTH MAXLENGTH MEDIATYPE NOTRUNCATE SET STATUSCODE STATUSTEXT, STATUSLEN < options for code conversion > CHARACTERSET CLIENTCONV © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Closing a session § EXEC CICS WEB CLOSE • Close a session with a remote server – will notify remote server – for notification, > use CLOSESTATUS(CLOSED) on WEB SEND > write a “Connection: close” header with WRITE HTTPHEADER and then WEB SEND – if the remote server sent a “Connection: close” header > can find out by READ HTTPHEADER > no further messages can be sent for the session > issue WEB CLOSE 113 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Other WEB APIs § EXEC CICS WEB PARSE URL • Breaks down a URL string into > scheme, host, port, path, query string • validate the construction of a URL • use on a subsequent WEB OPEN to open a session § EXEC CICS WEB EXTRACT • obtains information about an HTTP request > applies to both inbound and outbound HTTP requests • use SESSTOKEN option for CICS as an HTTP client – extract information about the most recent outbound request 115 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Exits for CICS as an HTTP client § XWBOPEN • called during WEB OPEN, before the session is open • Usage – determine usage for proxy servers – apply a security policy to the host name – etc. § XWBSNDO • called during WEB SEND or WEB CONVERSE, before sending the request – for chunked transfer-coding, only called for the first WEB SEND • Usage – apply a security policy to the host and path component – etc. 117 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Code conversion changes in CICS TS V 3. 1 § Changes for DFHCNV § Support for Unicode UTF-8, UTF-16 formats § Code conversion in CICS as an HTTP server § Code conversion in CICS as an HTTP client 119 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Changes for DFHCNV § Code conversion table not required • code pages are specified in – WEB/DOCUMENT APIs for web-aware applications – Analyzer program for non web-aware applications – URIMAP definition for static responses • DFHCNV can still be used – for migration purposes – specify which DFHCNV entry to use in the analyzer 121 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Support for Unicode UTF-8, UTF-16 formats § Support for Unicode • CICS now provides codepage conversions to and from UTF-8 and UTF-16 – CICS as an HTTP server – CICS as an HTTP client • uses the z/OS conversion services – conversion facility must be enabled > documented in “z/OS Support for Unicode Using Conversion Services” • Conversions to and from Unicode can be specified in – WEB APIs – Analyzer program • DFHCNV cannot be used to specify Unicode conversion 123 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Setting up the conversion service § Create conversion image • Run the Image generator utility • Sample JCL supplied – CUNJIUTL in SCUNJCL library Unicode EBCDIC CCSID Unicode //CVIMAGE JOB MSGCLASS=X, MSGLEVEL=(1, 1), REGION=4 M //CUNMIUTL EXEC PGM=CUNMIUTL //STEPLIB DD DISP=SHR, DSN=SYS 1. LINKLIB //SYSPRINT DD SYSOUT=* //TABIN DD DISP=SHR, DSN=SYS 1. SCUNTBL //SYSIMG DD DISP=SHR, DSN=SYS 1. IMAGES(CUNIMG 02) //SYSIN DD * CONVERSION 1200, 037; Generated conversion image CONVERSION 037, 1200; /* § Setup the parmlib • Copy the generated conversion image to the parmlib • Create parmlib member CUNUNIxx – Specify UNI=xx in IEASYSnn REALSTORAGE 1200 IMAGE CUNIMG 02; § Activate the environment Storage size to load the conversion image Conversion image to be activated • Re-IPL or SET UNI=xx command • DISPLAY UNI, ALL command to display current settings 125 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Code conversion in CICS as an HTTP server § Specifying code conversion • On WEB APIs – Specify SERVERCONV(SRVCONVERT) for conversion > Default is NOSRVCONVERT – On receive > CICS normally identifies the character set from the “Content-Type” header - if there is no header, ISO-8859 -1 is assumed - use CHARACTERSET option on WEB RECEIVE for other is required > HOSTCODEPAGE on WEB RECEIVE to identify the EBCDIC code page - default is LOCALCCSID in SIT – On send > CHARACTERSET on WEB SEND - default is ISO-8859 -1 > HOSTCODEPAGE on WEB SEND - default is LOCALCCSID in SIT - omit HOSTCODEPAGE if using DOCTOKEN 127 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Code conversion in CICS as an HTTP server… § Specifying code conversion • Analyzer program – for non web aware programs – wbra_characterset and wbra_hostcodepage parameters > Or, a key for an entry of DFHCNV (wbra_dfhcnv_key) • In URIMAP definition – for static responses – CHARACTERSET and HOSTCODEPAGE attributes 129 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Code conversion in CICS as an HTTP client § Specifying code conversion • On WEB APIs – Specify CLIENTCONV(CLICONVERT) for conversion > Default is CLICONVERT – On send, > CHARACTERSET on WEB SEND - ISO-8859 -1 is the default > CODEPAGE on WEB OPEN identifies the EBCDIC code page - default is LOCALCCSID in SIT – On receive, > Character set is identified in the “Content-Type” header - ISO-8859 -1 is the default > CODEPAGE on WEB OPEN - default is LOCALCCSID in SIT 131 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Other changes § Changes to URMs § Changes to definitions § API changes § JCICS API changes § Supplied transaction changes § Monitoring and statistics changes 133 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Changes to URMs § Analyzer program • now optional, can be specified in URIMAP • but still can be used to – change application programs, alias transaction, userids, code conversions, etc. – include monitoring or audit actions • attributes of the URIMAP can be passed to the analyzer and overridden – CHARACTERSET, HOSTCODEPAGE, CONVERTER, TRANSACTION, USERID, PROGRAM • some input and output parameter changes – new output to indicate pre-CICS TS V 3 compatibility processing > for non-Web aware programs to be processed as before – parameters relating to code conversion • New supplied analyzer program DFHWBAAX – To be invoked after no matching URIMAP found § Converter program • optional, can be specified in URIMAP and analyzer program • can be used to – convert HTTP data to/from commareas – make more than one application program to be called for the same request 135 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Changes to URMs § Web error program • DFHWBEP invoked for new situations – HTTP/1. 1 specific error responses > HTTP request/response format inconsistencies - Methods - headers > New error status codes – new error situations > URIMAP disabled, virtual host disabled > resource cannot be found on a static response > other unexpected errors processing URIMAPs • New supplied Web error program DFHWBERX – invoked when used with the new supplied DFHWBAAX analyzer program > 404 (Not Found) is returned to the client 137 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Changes to definitions § SIT • LOCALCCSID § RDO • URIMAP • DOCTEMPLATE – HFSFILE attribute • TCPIPSERVICE – PROTOCOL attribute – MAXDATALEN attribute 139 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 API changes § new API • • • EXEC CICS WEB PARSE EXEC CICS WEB OPEN EXEC CICS WEB CONVERSE EXEC CICS WEB CLOSE EXEC CICS CONVERTTIME * all APIs are threadsafe § changed API • • • 141 EXEC CICS WEB EXTRACT EXEC CICS WEB SEND EXEC CICS WEB RECEIVE EXEC CICS WEB WRITE HTTPHEADER EXEC CICS WEB READ HTTPHEADER EXEC CICS WEB STARTBROWSE HTTPHEADER EXEC CICS WEB READNEXT HTTPHEADER EXEC CICS WEB ENDBROWSE HTTPHEADER EXEC CICS FORMATTIME * all APIs are now threadsafe © 2005 IBM Corporation
CICS Transaction Server V 3. 1 JCICS API changes § Extended to support new features • HTTPSession class – open(), send(), receive(), converse(), close() • HTTPRequest class – set. Path(), set. Method(), set. Body(), set. Conversion, write. Header, etc. • HTTPResponse class – get. Status. Code(), get. Status. Text(), get. Header, get. Content, etc. 143 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 SPI changes § new SPI • • • EXEC CICS CREATE URIMAP EXEC CICS DELETE URIMAP EXEC CICS INQUIRE URIMAP EXEC CICS SET URIMAP EXEC CICS INQUIRE HOST EXEC CICS SET HOST § changed SPI • • • 145 EXEC CICS CREATE DOCTEMPLATE EXEC CICS INQUIRE DOCTEMPLATE EXEC CICS SET DOCTEMPLATE EXEC CICS CREATE TCPIPSERVICE EXEC CICS INQUIRE TCPIPSERVICE EXEC CICS SET TCPIPSERVICE © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Changes to supplied transaction § CWXU • New transaction for non-HTTP requests – PROTOCOL(USER) in TCPIPSERVICE • No URIMAP matching – Attaches analyzer program § CWXN • Internal processing change – – 147 URIMAP matching analyzer program is optional handling for HTTP/1. 1 asynchronous receive © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Changes to monitoring and statistics § Monitoring • fields added to DFHWEBB group – count/bytes for sends and receives in CICS as an HTTP client > WBREDOCT, WBWRTOCT, WBRCVIN 1, WBCHRIN 1, WBSNDOU 1, WBCHROU 1, WBPARSCT, WBBRWOCT § Statistics • URIMAP statistics – number of URIMAP matches – number of redirection, static response, application response, etc. 149 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Statistics sample 151 -URIMAPs - Global +________ 0 URIMAP reference count. . . Host/Path no match count. . Host/Path match disabled. . Redirected. . Analyzer used. . . . Static content delivered. . Dynamic content delivered. . PIPELINE requests. . . 0 Scheme (HTTP) requests. . . Scheme (HTTPS) requests. . . Scheme (WSMQ) requests. . . 0 Virtual host disabled count. . . : : : : 0 0 0 0 -URIMAPs +_______ 0 URIMAP Name. . . . URIMAP Enable Status. . URIMAP Usage. . . URIMAP Scheme. . . 0 URIMAP Host. . . . URIMAP Path. . . . 0 TCPIPSERVICE name. . WEBSERVICE name. . . PIPELINE name. . . 0 Templatename. . . HFS File. . . . 0 Analyzer. . . . Converter. . . . Transaction ID. . . Program name. . . 0 Location for redirection 0 URIMAP reference count. Host/Path match disabled Redirected. . . : : : : : SAMPLE Enabled Server HTTP www. hursley. ibm. com / TCPS 1 . . Yes SAMPLE 3 CWBA DFH 0 STAT -Virtual Hosts +_______ 0 Virtual Host name. . . . : TCPIPSERVICE name. . . . : Virtual Host Enable Status. . : www. hursley. ibm. com TCPS 1 Enabled 0 0 0 © 2005 IBM Corporation
CICS Transaction Server V 3. 1 Summary § CICS now supports HTTP/1. 1 • New features with HTTP/1. 1 includes – persistent connection – Chunking and pipelining – HTTP date and time format § URIMAP resource for simplified management • Can be used in place of analyzer programs § WEB API for outbound HTTP requests § Unicode conversion support 153 © 2005 IBM Corporation