The WEB RECEIVE command or the WEB CONVERSE command is used to
receive the response from the server. (The WEB CONVERSE command combines the
functions of the WEB SEND and WEB RECEIVE commands.) The WEB READ HTTPHEADER
command or the HTTP header browsing commands are used to examine the headers.
The time that the application is prepared to wait to receive a response
is indicated by the RTIMOUT value specified on the transaction profile definition
for the alias transaction.
The timeout limit does not apply to reading the headers of the response.
When
the period specified by RTIMOUT expires, CICS® returns a TIMEDOUT response to the
application. An RTIMOUT value of zero means that the application is prepared
to wait indefinitely. The default setting for RTIMOUT on transaction profile
definitions is zero, so it is important to check and change that setting.
Using the WEB
RECEIVE or WEB
CONVERSE command:
- Specify the session token for this connection, using the SESSTOKEN
option.
- Specify data areas to receive the HTTP status code sent by the
server, and any text returned by the server to describe the status code. Note that the data is returned in its unescaped form.
- Specify a data area to receive the media type of the response body.
- Receive the response body by specifying either the INTO option
(for a data buffer), or the SET option (for a pointer reference),
and the LENGTH option. The data is returned in its escaped form,
and converted into a code page suitable for the application, unless you request
otherwise.
- If you want to limit the amount of data received from the response
body, specify the MAXLENGTH option. If you want to retain, rather than discarding,
any data that exceeds this length, specify the NOTRUNCATE option as well. Any remaining data can be obtained using further WEB RECEIVE commands. If the data has been sent using chunked transfer-coding, CICS assembles
the chunks into a single message before passing it to the application, so
the MAXLENGTH option applies to the total length of the entity body for the
chunked message, rather than to each individual chunk.
- If code page conversion is not required for the response
body, specify the appropriate conversion option (depending on whether you
are using the WEB RECEIVE command or the WEB CONVERSE command), so that CICS does
not convert the response body. The default is that conversion
should take place, and in that case CICS converts the body of the server's
response into the default code page for the local CICS region, or any alternative EBCDIC
code page that you specified on the WEB OPEN command.
Note: If
you receive an entity body that has been zipped or compressed, as indicated
by a Content-Encoding header on the message, make sure that you suppress code
page conversion. CICS does not decode these types of message for you,
and if code page conversion is applied the results could be unpredictable.
If you do not want to receive zipped or compressed entity bodies, you can
specify this using an Accept-Encoding header on your request to the server.
When you issue the WEB RECEIVE or WEB CONVERSE command, CICS returns
the response body and the information from the status line.
- Examine the HTTP headers of the server's response using the appropriate CICS commands:
- If you want to read a specific HTTP header that you know the server
provides, use the WEB READ HTTPHEADER command to examine the contents
of that header. Your application program must provide a buffer which will
receive the contents of the header. CICS returns a NOTFND condition if the
header is not present in the request.
- If you want to browse all the HTTP headers in the response, use a WEB
STARTBROWSE HTTPHEADER command to begin browsing the header lines.
Use a WEB READNEXT HTTPHEADER command to retrieve the header
name and header value for each line. Your application program must provide
two buffers: one will receive the name of the header, and one will receive
its contents. CICS returns
an ENDFILE condition when all headers have been read. Use a WEB ENDBROWSE HTTPHEADER command when your program
has retrieved all the header information of interest.
Remember to include the session token on each of the HTTP header commands.
- Process the server's response and execute the application's business
logic. If the response had a "normal" or informational status code,
such as 200 (OK), you can process the response as normal. (The status code
is received when you issue the WEB RECEIVE command.) If the response
had a status code indicating an error or requesting further action, you should
carry out alternative processing to account for this. HTTP status code reference for CICS Web support has basic guidance on
responding to status codes.
- If you sent a pipelined sequence of requests, receive the rest
of the responses from the server using further WEB RECEIVE commands. CICS holds
the responses and returns them to the application program in the order that CICS received
them from the server. A server that handles pipelined requests will provide
the responses in the same sequence in which the requests were received.
Tip: When you are receiving responses to pipelined
requests, if you are using multiple WEB RECEIVE commands to receive overlength
message bodies, be careful to keep track of how many WEB RECEIVE commands
you have issued. You might find it more convenient to receive the whole body
for each of these responses in a single WEB RECEIVE command.