DFHWBEP, web error program

DFHWBEP receives a parameter list from CICS®, giving information about the error situation, and a block of storage containing the default HTTP response, including status code and status text, that CICS plans to send to the web client. The program can use or modify the default response or create and send its own response using the EXEC CICS WEB and DOCUMENT API commands. DFHWBEP is user-replaceable.

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

Assessing the error situation

The parameter list passed to DFHWBEP by CICS contains the 3-digit HTTP status code that CICS has used in the default response. The parameter list also supplies information that identifies the error situation, such as an error code, abend code, CICS message number, response and reason codes, and the name of the program in which the error has occurred.

If you customize DFHWBEP, make sure that you are 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. Each status code can be used by CICS web support for various purposes. Any HTTP responses with status codes that are not known to your program must be passed through unchanged.

In addition to examining the parameter list provided by CICS, you might want to use the EXEC CICS WEB EXTRACT command and the EXEC CICS EXTRACT TCPIP command, to examine the request line and obtain other information relating to the web client request for which the error response is needed. You can also use the WEB READ HTTPHEADER command or the HTTPHEADER browsing commands to read the HTTP headers for the request. If the request was in an invalid state or timed out, these commands might not be available

Do not use the EXEC CICS WEB RECEIVE command, which receives the content of the web client request, in your web error programs. In the range of error situations handled by DFHWBEP, the web client request might have timed out, or it might be lacking required information, or it might have unanticipated and potentially malicious content, or it might have already been received by another application program. Receiving a request in any of these states can lead to problems or unpredictable results.

Creating and sending the error response

The parameter list provided by CICS includes a pointer to a block of storage, containing the default HTTP response for the error detected and also a parameter giving the length of the complete response message. The block of storage contains a complete HTTP response, including the status line, HTTP headers, and message body.

The web error program can choose one of the following actions:
  1. Leave the default response unchanged and allow CICS to send it to the web client. Take this action for any HTTP responses with status codes that are not known to your program, or in cases where you have assessed the situation and found that the default response is appropriate.
  2. Use the EXEC CICS WEB and DOCUMENT API commands to create a new response and send it to the web client. CICS can then provide more assistance with checking the message. The default response is discarded. Use the WEB WRITE HTTPHEADER command to write HTTP headers for the response, and use the WEB SEND command to assemble and send the response. You must specify ACTION(IMMEDIATE) in your command, because the default of ACTION(EVENTUAL) is not permitted with DFHWBEP. Writing HTTP headers for a response, Producing an entity body for an HTTP message, and Sending an HTTP response from CICS as an HTTP server explain how to create and send a response using the API commands.
  3. Modify the default response manually in the block of storage, update the length parameter accordingly, and allow CICS to send it to the web client. Use this action if you want to make only minor changes to the default response, such as replacing the default message body with a short piece of text. You must be careful to ensure that the HTTP response remains valid and that the correct length is stated.
  4. Construct a new HTTP response manually in a new block of storage, pass back the address of the new block of storage and the length of the new response, and allow CICS to send it to the web client. The default response is discarded. This action is no longer recommended, because CICS cannot provide full assistance with checking a message constructed in this way. If you have a version of DFHWBEP that was customized before CICS Transaction Server for z/OS®, Version 3 Release 2 and it acts in this way, consider replacing it with an HTTP response constructed and sent using the EXEC CICS WEB and DOCUMENT API commands.

Correct content for the error response

Whether you use the EXEC CICS WEB and DOCUMENT API commands to create a new response, or you modify the default response manually in the block of storage, or construct a new HTTP response manually in a new block of storage, you can modify all the items in the error response. However, you must ensure that the HTTP response remains valid and appropriate and, if you are working with the response manually in a block of storage, that the correct length is stated.

The response must contain an HTTP version, status code, status text, any HTTP headers that are required, and the message body. The format of the response must comply with the HTTP protocol specification to which you are working (HTTP/1.0 or HTTP/1.1). If you are using the API commands, CICS provides assistance with all these elements.

Note the following guidance for individual items in the error response:

The HTTP version (HTTP/1.1 or HTTP/1.0)
In the default response, the version is decided by CICS according to the HTTP version of the web client. If you are working with the default response in the block of storage, do not modify this element of the response. If creating a new response using the API commands, use the WEB EXTRACT command to identify the HTTP version of the web client, and tailor your response accordingly. The HTTP version used by the web client can affect your choice of HTTP headers, status code, and message content for the response. HTTP/1.0 clients might not understand the more advanced features described in the HTTP/1.1 specification.
The numeric status code (for example, 404 or 500)
CICS chooses a status code for the default response. Be cautious when modifying this element of the default response or choosing a status code for your new response. HTTP status code reference for CICS web support lists the status codes and why they are used. The HTTP/1.1 specification has more information about all the status codes and the requirements for their correct use. If you choose a different status code from the one selected by CICS web support, make sure that your usage complies with the HTTP/1.1 specification. In particular, check that the status code is suitable for the HTTP version of the web client. For non-HTTP errors, CICS always uses a 400 status code.
The reason phrase, or status text (for example, Not Found)
You may modify this element of the default response or supply your own reason phrase for a new response. The reason phrases suggested by the HTTP/1.1 specification (for example, "Not Found" or "Bad Request") are recommended but optional. The HTTP/1.1 specification states that the reason phrases for each status code can be replaced by local equivalents.
HTTP headers
The default response contains the headers that CICS has written for the response; for example, Date and Server headers. If you create a new response using the API commands, CICS adds these headers automatically when you send the response. HTTP header reference for CICS web support lists the headers that CICS can write. The headers written by CICS are appropriate for the HTTP version of the message. Do not remove them if you are working with the default response, because they might be required for compliance with the HTTP specifications. You can add further HTTP headers for the response if appropriate. Check that the HTTP/1.1 specification allows the use of the headers in that context. If you have selected a different status code, some headers might be required by the HTTP/1.1 specification.
Message body
The message body for the default response repeats the status code and reason phrase that are given in the release line. You can modify this element of the default response, or supply your own message body for a new response. For many status codes, the body of the message can be used to provide you with further information. Some status codes cannot be accompanied by a message body.

Code page conversion

The default HTTP response in the block of storage is passed to DFHWBEP in the EBCDIC code page 037.

When you use EXEC CICS WEB API commands in the web error program to produce a new error response and send it to the web client, code page conversion takes place as you specify in the commands, in the same way as for any other program that uses the EXEC CICS WEB API commands.

DFHWBEP cannot specify code page conversion settings for a response produced in a block of storage. If you modify the default error response in the block of storage, or supply a new error response in a new block of storage, and return it to CICS for sending, CICS assumes that the response provided in the block of storage is also in the EBCDIC code page 037. CICS performs code page conversion on the response to convert it to a suitable ASCII character set before returning it to the client. If an analyzer program is involved in the processing path and has set parameters for code page conversion (as individual server and client code page parameters, or as a DFHCNV key), CICS uses these options for code page conversion. If no analyzer program is involved, or the analyzer was not called before the error occurred, the ISO-8859-1 character set is used for the response. If this outcome is not suitable, use the EXEC CICS WEB API commands to produce the response instead.



dfhtlh1.html | Timestamp icon Last updated: Sunday, 4 June 2017