Selecting escaped or unescaped data from an analyzer program

The HTTP request which is passed to the analyzer program for parsing is in its escaped form. Reserved or excluded characters in the URL, or in form data in the message body, are presented as a %xx sequence, wherexx is the ASCII hexadecimal representation of the reserved character. The analyzer can pass the request in a 32K block of storage to subsequent processing stages in its escaped form, with the escape sequences still present, or in its unescaped form, with the escape sequences converted back to the original characters. Web-aware application programs using the EXEC CICS WEB API commands do not use this mechanism to receive the response, and they request unescaping directly from CICS®.

Attention: This topic contains Product-sensitive Programming Interface and Associated Guidance Information.

Defining local resources for DPL explains escaping and its purpose. Escaping and unescaping only applies to the following elements of the HTTP request:

The URL portion of the request line, including any query string. The query string might be data from a form with the GET method.
Form data returned from a form with the POST method and the default encoding application/x-www-form-urlencoded. This data is presented in the message body. Choosing the access method for MRO explains more about form data.

If the request in the 32K block of storage is to be passed on in unescaped form, the analyzer can convert the data from escaped to unescaped form, or have CICS perform the conversion.

To pass the request in escaped form, set WBRA_UNESCAPE to WBRA_UNESCAPE_NOT_REQUIRED in your analyzer. WBRA_UNESCAPE_NOT_REQUIRED is the default value.
To pass the request in unescaped form and have CICS perform the conversion, set WBRA_UNESCAPE to WBRA_UNESCAPE_REQUIRED in your analyzer.
To pass the request in unescaped form after the analyzer has performed the conversion, set WBRA_UNESCAPE to WBRA_UNESCAPE_NOT_REQUIRED.

Web-aware application programs using the EXEC CICS WEB API commands do not use the COMMAREA mechanism to receive and send the response, and they request unescaping directly from CICS. For web-aware applications that use the EXEC CICS WEB API commands, when you extract form data from a request using the WEB READ FORMFIELD command or form field browsing commands, CICS performs the unescaping, and the data is returned in its unescaped form. When you extract a query string from a request using the WEB EXTRACT command, the data is returned in its escaped form.

If you are writing an application with a COMMAREA interface that can be run either through CICS web support or through the CICS business logic interface, ensure that WBRA_UNESCAPE is set to WBRA_UNESCAPE_NOT_REQUIRED, and that any unescaping is delegated to the application. If this is not done, the application is passed unescaped data by the CICS business logic interface, and escaped data by CICS web support, which might cause unpredictable results.