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.
Reference information for DFHWBEP, Web error program has a listing and technical
descriptions of all the parameters in the COMMAREA passed to DFHWBEP.
The parameter list passed to DFHWBEP contains the three-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, message
number, response and reason codes, and the name of the program where 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 may be used by CICS Web support for a variety of purposes. Any HTTP
responses with status codes that are not known to your program should be passed
through unchanged.
The parameter list also includes a pointer to a buffer (
wbep_response_ptr)
containing the default HTTP response returned by CICS for the error detected, and also the
length of the response (
wbep_response_len). The buffer contains
a complete HTTP response, including the status line, HTTP headers and message,
and the length is the length of the complete response message. The Web error
program can:
- Leave the response unchanged.
- Use the EXEC CICS WEB and DOCUMENT API commands to
create a new response and send it to the Web client. This action is recommended
if you want to change the response, because it means that CICS can provide
more assistance with checking the message. A response that you create in this
way replaces the default response, which is discarded. The WEB WRITE HTTPHEADER
command can be used to write HTTP headers for the response, and the WEB SEND
command can be used to assemble and send the response. You must specify ACTION(IMMEDIATE)
in your command, otherwise the response will not be sent.
- Modify the response to be returned, and update the length in wbep_response_len accordingly.
- GETMAIN a new buffer, build a new HTTP response, and pass back the address
of the new buffer in wbep_response_ptr and the length of
the new response in wbep_response_len.
It is possible to modify all the items in the response, but
note the following guidance for individual items:
- The HTTP version (HTTP/1.1 or HTTP/1.0)
- This is decided by CICS according to the HTTP version of the Web client.
Do not modify this element of the response.
- The numeric status code (for example, 404 or 500)
- Be cautious about modifying this element of the response. HTTP status code reference for CICS Web support lists
the status codes used by CICS Web support, and the reasons 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 decide that a different
status code is more appropriate than the one selected by CICS Web support,
make sure your usage is compliant with the requirements in 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 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 says that the reason
phrases for each status code may be replaced by local equivalents.
- HTTP headers
- The default response passed to DFHWBEP contains the headers that CICS has written
for the response (for example, Date and Server headers). The headers written
by CICS are
appropriate for the HTTP version of the message, and should not be removed,
because they might be required for compliance with the HTTP specifications. HTTP header reference for CICS Web support lists the headers that CICS can
write. You may 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 may be required
by the HTTP/1.1 specification.
- Message body
- The default message body repeats the status code and reason phrase that
are given in the release line. You may modify this element of the response.
For many status codes, the body of the message may be used to provide further
information to a human user. Some status codes cannot be accompanied by a
message body.