CICS® Transaction Server for z/OS®, Version 3 Release 1 is
designed to support your existing CICS Web support architecture for both
Web-aware and non-Web-aware application programs. The EXEC CICS WEB API
command changes are designed to allow existing Web-aware application programs
that send and receive HTTP messages to work unchanged, until you choose to
migrate them to take advantage of the enhancements that are now available.
If you continue to use existing CICS Web support applications, note these
migration points:
- If you are using CICS Web support to process non-HTTP requests,
specify the new USER protocol on the TCPIPSERVICE definition that defines
the port for these requests.
This also applies to HTTP requests
with nonstandard request methods, which are now rejected if they are received
on the HTTP protocol (previously, they were accepted and processed as non-HTTP). Processing for all non-HTTP requests must now be carried out under the
USER protocol, so that they are not subjected to the basic acceptance checks
which CICS carries
out for requests using the HTTP protocol. The requests are flagged as non-HTTP
and passed unchanged to the analyzer program for the TCPIPSERVICE. CICS Web support
facilities are used for handling the request, but no acceptance checks are
carried out for messages sent and received using this protocol. Note: Because
only one active TCPIPSERVICE definition can exist for each port, non-HTTP
requests can no longer use the same port as HTTP requests. The well-known
port numbers 80 (for HTTP) and 443 (for HTTPS) must have the HTTP protocol
and therefore cannot accept non-HTTP requests. Web clients must specify any
changed port in the URL for their requests.
- Check the settings for your TCPIPSERVICE resource definitions
with the HTTP protocol.
- The SOCKETCLOSE attribute must no longer have a zero setting
(SOCKETCLOSE(0)). A zero setting for SOCKETCLOSE means that CICS closes
the connection immediately after receiving data from the Web client, unless
further data is waiting. This means that persistent connections cannot be
maintained. A non-zero setting for SOCKETCLOSE enables persistent
connections with both HTTP/1.1 clients, and HTTP/1.0 clients (where the client
supports this).
- The new MAXDATALEN option should be specified to limit the maximum
length of data that may be received by CICS as an HTTP server. This
setting helps to guard against denial of service attacks involving the transmission
of large amounts of data.
- If you are using SSL, there are some changes to the security
options available on the TCPIPSERVICE resource definition.
- The analyzer program now allows you to supply codepage
conversion parameters to CICS Web Support instead of supplying the name of
a DFHCNV table entry. If you want to continue to use an analyzer program
that you coded in an earlier CICS release to reference DFHCNV, you must either continue
to supply the entries in the code page conversion table, or change the analyzer
program. Changing the analyzer program involves coding two new
output parameters to specify the client and server code pages, in place of
the output parameter that specified the name of a DFHCNV entry. If you do
this, you do not need to migrate your DFHCNV entries. Code page conversion for CICS Web support explains the new processes
for code page conversion.
- If you have modified the user-replaceable Web error program
DFHWBEP to customize the HTTP responses provided in error situations, be aware
that CICS now
uses additional status codes, and uses some existing status codes in a wider
range of situations.
- Check that your program is using an appropriate range of input
parameters to identify the situation to which the customized response applies,
rather than relying on the status code alone. The error code, abend
code, message number, response and reason codes, or program name can be used
to identify the situation that has given rise to the HTTP response. If these
checks are not made, you might find that where CICS is using the status code for a new
purpose, an inappropriately customized response is returned.
- Check that your program includes logic to pass through unchanged
any HTTP responses with status codes that are not known to the program.
- The DFHWBCLI interface is still supported in CICS Transaction Server for z/OS, Version 3 Release 1. To
gain enhanced functionality, you can migrate HTTP client applications that
used the DFHWBCLI interface, to use the EXEC CICS WEB API
commands for client requests (with the SESSTOKEN option). One important
difference to note is that in the EXEC CICS WEB API, the
use of a proxy server is specified by a user exit on the WEB OPEN command
(XWBOPEN), and the URL of the proxy server is supplied by that user exit. Support for HTTP client requests from CICS applications describes how HTTP client requests
can now be made.