The daily edition.

Scope: Rocket Enterprise Developer 12.0 for Eclipse (UNIX) and Rocket Enterprise Server 12.0 with Mainframe Subsystem Support (MSS), covering CICS Web Interface (CWI) request routing, analyzer programs, error handling, and security prerequisites.

In Rocket Enterprise Server, CICS Web Interface (CWI) support allows a CICS region to operate as both an HTTP server and an HTTP client for CICS Transaction Server 3.1 and later applications. Rather than treating every inbound HTTP request as a single fixed pipeline, CWI splits request handling across port-level listener definitions (TCPIPSERVICE), URI pattern matching (URIMAP), optional per-port analyzer programs, converter programs, and two distinct error-handling programs (CICS Web Interface Support).

1. Port Listeners and URIMAP Dispatching

Every CWI server deployment requires two foundational resources: a TCPIPSERVICE definition for each inbound HTTP port and a URIMAP definition that governs how matching requests are processed (CICS Web Interface Support). When you create a TCPIPSERVICE in ESCWA for a target HTTP port, the Enterprise Server communication layer dynamically starts a listener on that port (To enable CICS Web interface support).

A DEFINE URIMAP definition (USAGE(SERVER|CLIENT|PIPELINE)) matches requests by SCHEME(HTTP|HTTPS), HOST(name), and PATH(string) (which supports * wildcard matching). Note that the GROUP name on a URIMAP cannot begin with DFH, because Mainframe Subsystem Support reserves that prefix for system groups (DEFINE URIMAP).

For USAGE(SERVER), a URIMAP can take one of two paths (DEFINE URIMAP):

• Static response delivery: Using MEDIATYPE, CHARACTERSET (default iso-8859-1), HOSTCODEPAGE (default 037), and either a CICS document template (TEMPLATENAME) or a file (HFSFILE).
• Dynamic application execution: Associating the URI with a TCPIPSERVICE, an optional analyzer flag (ANALYZER(NO|YES)), a CONVERTER program to transform request and response payloads, an alias TRANSACTION (default CWBA for USAGE(SERVER), or CPIH for USAGE(PIPELINE)), the target user application PROGRAM, and a transaction USERID.

Rocket documents the following DEFINE URIMAP syntax for an HTTPS server route (DEFINE URIMAP):

DEFINE URIMAP(SAMPURI) GROUP(SAMPGRP)
DESCRIPTION(Sample URIMAP for a server application response)
       STATUS(ENABLED) USAGE(SERVER) SCHEME(HTTPS) HOST(localhost)
       PATH(/tests/*) TCPIPSERVICE(TCPNOURM) ANALYZER(NO)
       CONVERTER(CICS) TRANSACTION(CWBA) PROGRAM(MYPROG) USERID(FREE)

2. How Analyzer Programs Override URIMAP Attributes

While a URIMAP statically binds a URL path to a converter, alias transaction, user ID, and target program, analyzer programs introduce dynamic request inspection. Each CICS Web support TCPIPSERVICE definition must use an analyzer program, and different TCPIPSERVICE ports can specify different analyzer programs (Analyzer Programs).

When the Analyzer option is enabled on a matching URIMAP (ANALYZER(YES)), the analyzer program inspects the HTTP request and can dynamically override four attributes defined on the URIMAP: Converter, Transaction, User Id, and Program (Analyzer Programs).

If no URIMAP is defined—or if the Analyzer field on the URIMAP is left blank—Enterprise Server falls back to DFHWBAAX as the default analyzer program for TCPIPSERVICE definitions with Protocol set to "HTTP" (Analyzer Programs). DFHWBAAX checks whether a matching URIMAP exists:

1. Matching URIMAP found: DFHWBAAX accepts the URIMAP's Transaction, Converter, and Program settings for downstream processing (Analyzer Programs).
2. No matching URIMAP found: DFHWBAAX routes control to the Web error application program DFHWBERX by setting DFHWBERX in the wbra_server_program output parameter (Analyzer Programs, Web Error Application program).

3. DFHWBERX vs. DFHWBEP in CWI Error Handling

Rocket Enterprise Server distinguishes between two CWI error programs (Web Error Application program, Web Error Program):

• DFHWBERX (Web Error Application program): Invoked when no URIMAP matches a request handled by DFHWBAAX (via wbra_server_program) or when explicitly named in a URIMAP's Program attribute to force an error response. It uses EXEC CICS WEB and DOCUMENT API commands to inspect the client request and build the response (Web Error Application program).
• DFHWBEP (Web Error Program): Receives a parameter list containing the HTTP status code, error code, abend code, message number, response/reason codes, and failing program name, along with a storage block holding the default HTTP response. It can modify any of those error items or replace the response using EXEC CICS WEB and DOCUMENT API commands (Web Error Program).

4. Security Prerequisites and Runtime Restrictions

Before deploying CWI applications into a secured region or writing custom analyzers, account for three documented constraints:

• MLDAP ESM transaction and PPT permissions: In a secured region using an MLDAP External Security Manager (ESM), the executing user ID must have permission to access CWXN (the default alias transaction on TCPIPSERVICE, or its configured replacement transaction), CWBA (the default server alias transaction), and the PPT entry for the target CICS program (To enable CICS Web interface support).
• Analyzer compilation and role limits: Analyzer programs must be compiled with ASCII or EBCDIC specified as the character set, and they can only be invoked when CICS acts as an HTTP server—never when CICS acts as an HTTP client or processes CICS Web services (Analyzer Programs).
• CWI API limitations: Trailer HTTP headers are not supported, outbound HTTP client connections cannot traverse an HTTP proxy, and the Action(Expect) option on WEB SEND requests is ignored (CICS Web Interface (Known Issues)).

Takeaway: Use URIMAP definitions for deterministic path-to-program routing, enable TCPIPSERVICE analyzer programs only when server-side HTTP requests need dynamic override or fallback logic, and grant CWXN, CWBA, and target PPT permissions up front in MLDAP-secured regions (To enable CICS Web interface support, Analyzer Programs).