Receiving an HTTP response

Use the WEB RECEIVE command or the WEB CONVERSE command to receive the response from the server. Use the WEB READ HTTPHEADER command or the HTTP header browsing commands to examine the headers.

1. Specify the session token for this use of the 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.
   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 is 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 discard, 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, so that CICS does not convert the response body.
   The default is that conversion takes place. In that case, CICS converts the body of the server response into the default code page for the local CICS region or into any alternative EBCDIC code page that you specified on the WEB OPEN command.

   Note: If you receive an entity body that has been 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 might be unpredictable. If you do not want to receive compressed entity bodies, use 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 response:
   • 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 to 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 to receive the name of the header and one to 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 relevant header information.
   Remember to include the session token on each of the HTTP header commands.
8. Process the server response and run the application business logic.
   If the response had a normal or information 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 must carry out alternative processing. 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 provides 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 track 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.