Receiving an HTTP response

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:

  1. Specify the session token for this connection, using the SESSTOKEN option.
  2. 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.
  3. Specify a data area to receive the media type of the response body.
  4. 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.
  5. 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.
  6. 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.

  7. 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.
  8. 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.
  9. 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.