Components of CICS web support

Base components

• TCP/IP support in CICS is provided by the CICS SO (sockets) domain, with network services (z/OS® Communications Server and access to a DNS server) supplied by z/OS.
• z/OS UNIX Systems Services are used as part of TCP/IP support, and the CICS region needs to access these components.
• Secure Sockets Layer (SSL) support is used to provide security for the CICS web support implementation. For a list of security protocols supported by CICS, see Support for security protocols.
• DOCCODEPAGE system initialization parameter specifies the default host code page that is used by CICS document template support.
• LOCALCCSID system initialization parameter specifies the coded character set identifier for the local CICS region (which is the code page that CICS considers as the default for application programs).
• TCPIP system initialization parameter activates CICS TCP/IP services at start.
• WEBDELAY system initialization parameter defines a timeout period for inactive CICS web tasks, only where the web 3270 bridge facility is involved. Timeout for other CICS web tasks is handled by the RTIMOUT value for the relevant transaction, or (for CICS as an HTTP server) by the SOCKETCLOSE attribute on the TCPIPSERVICE definition.
• The Sockets listener task (CSOL) detects inbound TCP/IP connection requests, and starts CICS web support by attaching the web attach task. CSOL can also identify those inbound requests, which are qualified to be processed by directly attached user transactions, and bypassing the web attach task. For more information, see Processing HTTP requests by using directly attached user transactions.
• Web attach tasks (CWXN, CWXU, or an alias) receive data from the web client and deal with initial processing of requests, including URIMAP matching, code page conversion of the HTTP headers, analysis of the request, and code page conversion of the message body. The tasks also pre-process chunked and pipelined messages that are received from a web client. If a static response is delivered (by using a URIMAP definition), the web attach task handles this processing as well.

Resource definitions

• TCPIPSERVICE resource definitions are used to define each port that you use for CICS as an HTTP server, including security options for connections on that port, and timeout and maximum size limits for inbound requests. They are not used for CICS as an HTTP client.
  Note: The TCPIPSERVICE resource definitions are for use only with the CICS provided TCP/IP services, and have nothing to do with the z/OS Communications Server IP CICS Sockets interface. The TCP/IP socket interface for CICS is supplied with z/OS Communications Server, which is a part of z/OS and does not use the CICS SO domain.
• URIMAP resource definitions match the URLs of requests from web clients, or requests to an HTTP server, and provide CICS with information on how to process the requests. URIMAP definitions incorporate, and can replace, the CICS web support processing functions that were provided before CICS Transaction Server for z/OS, Version 3 Release 1 by the analyzer program that is associated with the TCPIPSERVICE definition. URIMAP definitions can also be used to deliver a static response to a request from a web client, without involving an application program.
• TRANSACTION resource definitions are used to define alias transactions for HTTP request processing. CICS supplies a resource definition for a default alias transaction, CWBA. When the web attach task completes initial processing for the request, if an application-generated response is to be produced, an alias transaction handles the remaining stages of processing. These include receiving the request, running the application's business logic, construction of the HTTP response and code page conversion of the HTTP response. For those inbound requests that qualify for the option to bypass the web attach task before the alias transaction logic is started, CICS receives data from the web client and deals with initial processing of requests, including URIMAP matching, code page conversion of the HTTP headers, analysis of the request, and code page conversion of the message body.

User application programs

• Web-aware application programs can be designed for CICS web support, that uses the EXEC CICS WEB and EXEC CICS DOCUMENT application programming interfaces. For CICS as an HTTP server, these programs can receive and analyze HTTP requests and provide application-generated responses to the web client. For CICS as an HTTP client, a user application program in CICS can initiate an HTTP request to a server, and receive a response from it.
• COMMAREA applications, programs, which are linked to from another program that uses a COMMAREA interface, can be accessed by using CICS web support with a converter program to convert their output into HTML for transmission to a web client. Alternatively, you can write a web-aware application program that links to a COMMAREA application and uses its output to provide HTTP responses.
• 3270 display applications, programs, which are designed to communicate with 3270 terminals, can be accessed by using the Web Terminal Translation Application. The HTML output that is created by the Web Terminal Translation Application can be displayed in a web browser.

Programming interfaces

• Use the WEB command to interpret and construct HTTP requests and responses. Some commands are used for CICS as an HTTP server, some for CICS as an HTTP client, and some are for both forms of CICS web support.
• Use the DOCUMENT command to construct CICS documents to provide the body of a response or request that is sent out from CICS.
• Use the EXTRACT TCPIP command to obtain information about TCP/IP characteristics of the current transaction.
• Use the EXTRACT CERTIFICATE command to obtain information from the client certificate that is received over a TCP/IP service that specified client authentication.

CICS web support utility programs

• Analyzer programs are associated with TCPIPSERVICE definitions. They are used to interpret an HTTP request if a URIMAP definition specifies the use of an analyzer program, or if no URIMAP definition is present. CICS supplies a default analyzer program DFHWBAAX, which provides basic error handling, and a sample analyzer program DFHWBADX, which supports requests that use the URL format that CICS web support used before CICS TS 3.1. Either of these analyzers can be used as a basis for your own analyzer program.
• Converter programs can be used to decode an HTTP request and construct input to a user application program. Web-aware application programs do not normally require converter programs, but they might be needed by non-web-aware applications that were not designed for CICS web support. CICS does not supply a converter program. You can write a number of converter programs and select any converter program in your CICS region to process a request.
• Web error programs provide an error response to the web client when a request error or an abend occurs in the CICS web support process. CICS supplies the web error program DFHWBEP, which is used in most error situations, and the web error application program DFHWBERX, which is used with the default analyzer DFHWBAAX when URIMAP matching fails (and can be specified for other situations). The web error programs are user-replaceable, and they can be modified to customize or change the error response that is sent to the web client in each error situation.
• The Web Terminal Translation Application DFHWBTTA (and its aliases for alternative processing, DFHWBTTB and DFHWBTTC) can be used to create HTML output from programs, which are designed to communicate with 3270 terminals. The program uses the CICS 3270 bridge mechanism. Applications that do, and applications that do not use BMS, are both supported. No application program changes are needed to use this feature.
• The password expiry management program DFHWBPW is used when basic authentication is specified for the connection, and the user's password is expired. The program takes the user through the process of setting a new password. You can customize or replace the web pages that are presented to the user by DFHWBPW.

Document construction facilities

• z/OS UNIX Systems Services files can be served as the body of a response to an HTTP request from a web client.
• Document template support enables message bodies to be built from fragments of HTML, which are prepared offline.
• BMS macros construct HTML document templates from BMS map sets.

Code page conversion

CICS provides facilities to convert HTTP messages into a code page that is suitable for a user application program, or suitable for use on the Internet. CICS handles code page conversion that uses z/OS conversion services.

The code page conversion table (DFHCNV), which was required in earlier CICS releases, is not normally required for CICS web support in CICS Transaction Server for z/OS, Version 5 Release 3. The exception is if you want to use an analyzer program that you coded in an earlier CICS release to reference DFHCNV. In this case, you must either continue to supply the code page conversion table, or make an update to the analyzer program. For more information, see Upgrading entries in the code page conversion table (DFHCNV).