CICS Transaction Server V3.1 © 2005 IBM Corporation HTTP Support Upgrade Takahiro Ishiwatari [email protected]

CICS Transaction Server V3.1

© 2005 IBM Corporation

HTTP Support Upgrade

Takahiro [email protected]


© 2005 IBM Corporation3

Acknowledgements

The following are trademarks of International Business Machines Corporation in the United States, other countries, or both: IBM, CICS, CICS/ESA, CICS TS, CICS Transaction Server, DB2, MQSeries, OS/390, S/390, WebSphere, z/OS, zSeries, 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, 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.



Agenda

HTTP fundamentals

New features in CICS TS V3.1

• HTTP 1.1 compliance• HTTP processing in CICS

– CICS as an HTTP server

– CICS as an HTTP client

• Code conversion• Other changes



HTTP fundamentals

URI and URL

HTTP request and response

CICS Web Support processing in CICS TS V2

Information for HTTP specifications can be found at

HTTP/1.0 RFC 1945 ( http://www.w3.org/Protocols/rfc1945/rfc1945 )

HTTP/1.1 RFC 2616 (http://www.w3.org/Protocols/rfc2616/rfc2616 )



URI and URL

URL (Uniform Resource Locator)

• identifies a resource available on the internet– format specified in RFC1738 (http://www.ietf.org/rfc/rfc1738.txt)

URI (Uniform Resource Identifier)

• identifies an abstract or physical resource– format specified in RFC2396 (http://www.ietf.org/rfc/rfc2396.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

URL

URN

http:ftp:

news: telnet:

urn:

oasis:isbn:



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

http : / / www.ibm.com : 80 / Scripts / Global / nph-cc ? cc=at

scheme host port path query-string




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

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

Content-length: 80

(blank line)

aa=zzzzz&bb=yyyyy&cc=xxxxxx...

request line

header section

entity body




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

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



CICS Web Support processing in CICS TS V2

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

Listener

(CSOL)

Web Attach

transaction

（ CWXN ）

DFHCCNV (Header)

Analyzer

DFHCCNV (User Data)

Alias

transaction

(CWBA)

Business

Logic

Interface

(DFHWBBLI)

Converter (Decode)

Applicationor

3270 transaction via DFHWBTTA

Converter (Encode)

CICS

DFHCCNV



CICS Web Support processing in CICS TS V2…

example URL for the supplied analyzer

• for commarea applications

• for 3270 applications

HTTP requests can be processed via Web server

• Web server will invoke the Business Logic Interface (DFHWBBLI) via EXCI

http://hostname:80/CNV1/CWBA/USRPGM1

http://hostname:80/CICS/CWBA/DFHWBTTA/AMNU

Converterprogram

Aliastranid

Web Bridgeprogram

Targettranid

Converterprogram

Aliastranid

Targetprogram



CICS Web Support processing in CICS TS V2…

Outbound HTTP requests

• Linkable interface provided in CICS TS V2.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

DFHWBCLI

DFHWBCLI

LINK for Send

LINK for Receive

HTTP request

HTTP response

CICS

DFHWBCLILINK for Close



What’s new in CICS TS V3.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



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



HTTP/1.1 compliance…

New features that CICS provides for HTTP/1.1 compliance

• Supported methods• HTTP date and time formats• Persistent connections• Pipelining• Chunking



Supported Methods

Methods supported

• For HTTP/1.0 in CICS– GET, HEAD, POST, PUT, DELETE, LINK, UNLINK, REQUEUE

> RFC1945(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



Supported Methods and CICS handlingMethod received from

1.0 Client

received from

1.1 Client

send to

1.0 server

send to

1.1 server

GET Ignore Message body Ignore Message body sent to server

Invreq if body present

sent to server


PUT Pass to application Pass to application sent to server with body

Invreq if no body present

sent to server with body


POST Pass to application Pass to application sent to server with body


sent to server with body


HEAD Ignore Message body Ignore Message body sent to server


sent to server


LINK Pass to application 501 – not implemented Invreq Invreq

UNLINK Pass to application 501 – not implemented Invreq Invreq

REQUEUE Pass to application 501 – not implemented Invreq Invreq

DELETE Pass to application Pass to application sent to server sent to server

OPTIONS 501 – not implemented Handle all in CWXN

501 if not OPTIONS *

Invreq sent to server

Invreq if not OPTIONS *

TRACE 501 – not implemented Handle all in CWXN Invreq sent to server

CONNECT 501 – not implemented 501 – not implemented Invreq Invreq



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 : RFC 1123 format– Tuesday, 01-Apr-03 10:01:02 GMT : RFC 1036 format– Tue Apr 01 10:01:02 GMT : ANSI C’s asctime() format

• only generate the RFC 1123 format– Tue, 01 Apr 2003 10:01:02 GMT : 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



HTTP date and time stamp formats…

CICS will supply APIs to handle conversion

– EXEC CICS CONVERTTIME

• converts HTTP formats to ABSTIME

– EXEC CICS FORMATTIME

• converts ABSTIME to HTTP format• new options DATESTRING and STRINGFORMAT

– STRINGFORMAT specifies the type of format in cvda

– currently only 646 (RFC1123) is supported

> if DATESTRING present and STRINGFORMAT not specified, RFC1123 is used

EXEC CICS CONVERTTIME DATESTRING (‘Tue, 01 Apr 2003 10:01:02 GMT’)

ABSTIME (+003258180062000)

EXEC CICS FORMATTIME ABSTIME (+003258180062000) STRINGFORMAT (RFC1123)

DATESTRING (‘Tue, 01 Apr 2003 10:01:02 GMT’)



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

Socketclosesocket connection

CWXNCWBA

CWBA

CWBA

CICS



Persistent connections…

In CICS TS V3.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

CWXN

Socketclosesocket connection

CWXNCWBA

CWBA

CWBA

CICS



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

SEND

SEND

SEND

request A

request B

request C

request D

SEND

SEND

SEND

SEND

response A

response B

response C

response D

RECEIVE

RECEIVE

RECEIVE

RECEIVE

RECEIVE

RECEIVE

RECEIVE

RECEIVE

Client Server



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

• 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

SEND

SEND

SEND

request A

request B

request C

SEND

response A

response B

response C

RECEIVE

RECEIVE

RECEIVE

RECEIVE

SEND

RECEIVE

SEND

RECEIVE



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

• recipient will receive the message as a whole– recipient can verify that it received the complete message

SEND

SEND

SENDSEND

RECEIVE… …



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)



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 analyzer

- Invokes the converter program if required

- Invokes the target application

– may need to change port for migration



TCPIPSERVICE change …

MAXDATALEN ( 32KB | 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 32KB (default)– maximum is 0.5GB

SOCKETCLOSE

• Recommendation change– Formerly, SOCKETCLOSE(0) was recommended

– In CICS TS V3.1, recommendation is to not specify SOCKETCLOSE(0)

> SOCKETCLOSE(0) will fail to meet the requirements for HTTP/1.1



HTTP processing in CICS

CICS as an HTTP server

• Web client sends an HTTP request to CICS

CICS as an HTTP client

• CICS sends an HTTP request to a remote server

HTTP request

HTTP response

HTTP request

HTTP response

CICS

Web

Support

Outbound

HTTP

Support

CICS

Application

CICS

Application

CICS

CICS



CICS as an HTTP server

Processing changes in CICS TS V3.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



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 URIMAP ==> SAMPURI USAGE ==> ServerUniversal Resource Identifier SCHEME ==> HTTP HOST ==> www.ibm.com PATH ==> Scripts/Global/*Associated CICS resource ….Static Document Properties ….Redirection ….



URIMAP definition



CICS Web Support processing in CICS TS V3.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

Socket

Listener

(CSOL)

Web Attach

transaction

(CWXN)

DFHCCNV (Header)

Analyzer

DFHCCNV (User Data)

Alias

transaction

(CWBA)

Business

Logic

Interface

(DFHWBBLI)

Converter (Decode)

Applicationor

3270 transaction via DFHWBTTA

Converter (Encode)

DFHCCNV

CICS

URIMAP matching



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

HTTP response

CICS

Web

Support

CICS

CICSApplication



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



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



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

HTTP response

CICS

Web

Support

CICS

HFS

doctemplate



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

• 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

PATH ==> findout/pictures/*

HFSFILE ==> /u/facts/image/*

/findout/pictures/bluefish.jpg

/u/facts/image/bluefish.jpg



Redirection

Redirect to another location on the web• permanently or temporarily• can be changed by SET URIMAP command for redirection

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)

HTTP request

Redirected HTTP request

CWS

CICS

301/302 response



URIMAP definition

Urimap ==> Group ==> DEscription ==> STatus ==> Enabled Enabled | Disabled USAge ==> Server Server | Client | Pipeline UNIVERSAL RESOURCE IDENTIFIER SCheme ==> HTTP HTTP | HTTPS HOST ==> (Mixed Case) ==> PAth ==> (Mixed Case) ==>

==> ==> ==>

ASSOCIATED CICS RESOURCES TCpipservice ==> Analyzer ==> No No | Yes COnverter ==> TRansaction ==> PRogram ==> PIpeline ==> Webservice ==> (Mixed Case)



URIMAP definition…

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.



URIMAP definition (continued)

SECURITY ATTRIBUTES USErid ==> CIphers ==> CErtificate ==> (Mixed Case) STATIC DOCUMENT PROPERTIES Mediatype ==> (Mixed Case) CHaracterset ==> (Mixed Case) HOSTCodepage ==> TEmplatename ==> (Mixed Case) HFsfile ==> (Mixed Case) ==>

==> ==> ==>

REDIRECTION Redirecttype ==> None None | Temporary | Permanent Location ==> (Mixed Case) ==>

==> ==> ==> ==>



URIMAP definition (continued)…

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.



URIMAP valid attributesattributes USAGE(SERVER) USAGE(CLIENT) USAGE(PIPELINE)

STATUS ENABLED / DISABLED ENABLED / DISABLED ENABLED / DISABLED

SCHEME HTTP / HTTPS HTTP / HTTPS HTTP / HTTPS

HOST required required required

PATH required required required

TCPIPSERVICE optional n/a optional

ANALYZER YES / NO n/a n/a

CONVERTER optional n/a n/a

TRANSACTION optional n/a optional

PROGRAM optional n/a n/a

PIPELINE n/a n/a required

WEBSERVICE n/a n/a required

USERID optional n/a optional

CIPHERS n/a optional n/a

CERTIFICATE n/a optional n/a

MEDIATYPE optional n/a n/a

CHARACTERSET optional n/a n/a

HOSTCODEPAGE optional n/a n/a

TEMPLATENAME optional n/a n/a

HFSFILE optional n/a n/a

REDIRECTTYPE optional n/a optional

LOCATION optional n/a optional



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



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

http://204.146.81.99

DNSserver

GET /htp/cics/index.html HTTP/1.1

204.146.81.99

Host: www-1.ibm.com

DNS resolution

http://www-2.ibm.com

http://204.146.81.99

DNS resolution

GET /htp/cics/index.html HTTP/1.1

Host: www-2.ibm.com



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

www-1.ibm.com

www-2.ibm.com

www-3.ibm.com

Host: www-2.ibm.com

Host: www-1.ibm.com

Host: www-3.ibm.com

URIMAP3

Disabled

Enabled

EnabledURIMAP4

URIMAP1

URIMAP2

URIMAP5TCP/IPPORT

CICS

Host: www-4.ibm.comURIMAP7

URIMAP8

URIMAP6

www-4.ibm.com

Enabled

host name used



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



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



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



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



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?



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



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 CLOSE

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



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



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



URIMAP ==> SAMPURI USAGE ==> ClientUniversal Resource Identifier SCHEME ==> HTTP HOST ==> www.ibm.com:80 PATH ==> Scripts/Global/nph-ccAssociated CICS resource ….Static Document Properties ….Redirection ….

URIMAP definition

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



Can be supplied on WEB OPEN commands

Can be supplied on WEB SEND commands



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



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



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



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 >

ACTIONCLOSESTDOCTOKENFROM, FROMLENGTHMEDIATYPEMETHODPATH, PATHLENGTHQUERYSTRING, QUERYSTRLENURIMAP

< options for receiving >

INTOTOLENGTHMAXLENGTHMEDIATYPENOTRUNCATESETSTATUSCODESTATUSTEXT, STATUSLEN

< options for code conversion >

CHARACTERSETCLIENTCONV



Closing a session

EXEC CICS WEB CLOSE

• Close a session with a remote server– will not 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



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



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.



Code conversion changes in CICS TS V3.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



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



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



Setting up the conversion service

Create conversion image• Run the Image generator utility• Sample JCL supplied

– CUNJIUTL in SCUNJCL library

Setup the parmlib

• Copy the generated conversion image to the parmlib• Create parmlib member CUNUNIxx

– Specify UNI=xx in IEASYSnn

Activate the environment

• Re-IPL or SET UNI=xx command• DISPLAY UNI,ALL command to display current settings

//CVIMAGE JOB MSGCLASS=X,MSGLEVEL=(1,1),REGION=4M//CUNMIUTL EXEC PGM=CUNMIUTL//STEPLIB DD DISP=SHR,DSN=SYS1.LINKLIB//SYSPRINT DD SYSOUT=*//TABIN DD DISP=SHR,DSN=SYS1.SCUNTBL//SYSIMG DD DISP=SHR,DSN=SYS1.IMAGES(CUNIMG02)//SYSIN DD * CONVERSION 1200,037; CONVERSION 037,1200;/*

Generated conversion image

Unicode EBCDIC CCSID

EBCDIC CCSID Unicode

REALSTORAGE 1200IMAGE CUNIMG02;

Storage size to load the conversion image

Conversion image to be activated



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



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



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



Other changes

Changes to URMs

Changes to definitions

API changes

JCICS API changes

SPI changes

Supplied transaction changes

Monitoring and statistics changes



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



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



Changes to definitions

SIT

• LOCALCCSID

RDO

• URIMAP• DOCTEMPLATE

– HFSFILE attribute

• TCPIPSERVICE– PROTOCOL attribute

– MAXDATALEN attribute



API changes

new API• EXEC CICS WEB PARSE

• EXEC CICS WEB OPEN

• EXEC CICS WEB CONVERSE

• EXEC CICS WEB CLOSE

• EXEC CICS CONVERTTIME

changed API• 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 threadsafe

* all APIs are now threadsafe



JCICS API changes

Extended to support new features

• HTTPSession class– open(), send(), receive(), converse(), close()

• HTTPRequest class– setPath(), setMethod(), setBody(), setConversion, writeHeader, etc.

• HTTPResponse class– getStatusCode(), getStatusText(), getHeader, getContent, etc.



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

• EXEC CICS CREATE DOCTEMPLATE

• EXEC CICS INQUIRE DOCTEMPLATE

• EXEC CICS SET DOCTEMPLATE

• EXEC CICS CREATE TCPIPSERVICE

• EXEC CICS INQUIRE TCPIPSERVICE

• EXEC CICS SET TCPIPSERVICE



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– URIMAP matching

– analyzer program is optional

– handling for HTTP/1.1

– asynchronous receive



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, WBRCVIN1, WBCHRIN1, WBSNDOU1, WBCHROU1, WBPARSCT, WBBRWOCT

Statistics

• URIMAP statistics– number of URIMAP matches

– number of redirection, static response, application response, etc.



Statistics sample-URIMAPs - Global+________________0 URIMAP reference count . . . . : 0 Host/Path no match count . . . : 0 Host/Path match count. . . . . : 0 Host/Path match disabled . . . : 0 Redirected . . . . . . . . . . : 0 Analyzer used. . . . . . . . . : 0 Static content delivered . . . : 0 Dynamic content delivered. . . : 0 PIPELINE requests. . . . . . . : 00 Scheme (HTTP) requests . . . . : 0 Scheme (HTTPS) requests. . . . : 0 Scheme (WSMQ) requests . . . . : 00 Virtual host disabled count. . : 0

-URIMAPs+_______0 URIMAP Name. . . . . . . . . . : SAMPLE URIMAP Enable Status . . . . . : Enabled URIMAP Usage . . . . . . . . . : Server URIMAP Scheme. . . . . . . . . : HTTP0 URIMAP Host. . . . . . . . . . : www.hursley.ibm.com URIMAP Path. . . . . . . . . . : /0 TCPIPSERVICE name. . . . . . . : TCPS1 WEBSERVICE name. . . . . . . . : PIPELINE name. . . . . . . . . :0 Templatename . . . . . . . . . : HFS File . . . . . . . . . . . :0 Analyzer . . . . . . . . . . . : Yes Converter. . . . . . . . . . . : SAMPLE3 Transaction ID . . . . . . . . : CWBA Program name . . . . . . . . . : DFH0STAT0 Location for redirection . . . :0 URIMAP reference count . . . . : 0 Host/Path match disabled . . . : 0 Redirected . . . . . . . . . . : 0

-Virtual Hosts+_____________0 Virtual Host name. . . . . . . : www.hursley.ibm.com TCPIPSERVICE name. . . . . . . : TCPS1 Virtual Host Enable Status . . : Enabled



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 code conversion support

Documents

CICS Transaction Server V3.1 © 2005 IBM Corporation HTTP Support Upgrade Takahiro Ishiwatari [email protected]