Start of change

WEB RECEIVE (Client)

Receive an HTTP response for CICS® as an HTTP client.

Read syntax diagramSkip visual syntax diagram
WEB RECEIVE (CICS as an HTTP client)

>>-WEB--RECEIVE--SESSTOKEN(data-value)-------------------------->

>--+----------------------+--+------------------------+--------->
   '-MEDIATYPE(data-area)-'  '-STATUSCODE(data-value)-'   

>--+----------------------------------------------+------------->
   '-STATUSTEXT(data-area)--STATUSLEN(data-value)-'   

>--+-INTO(data-area)-+--LENGTH(data-area)----------------------->
   '-SET(ptr-ref)----'                      

>--+-----------------------+--+------------+-------------------->
   '-MAXLENGTH(data-value)-'  '-NOTRUNCATE-'   

>--+------------------+----------------------------------------><
   '-CLIENTCONV(cvda)-'   

Conditions: INVREQ, LENGERR, NOTOPEN, IOERR, TIMEDOUT

This command is threadsafe.

Description

WEB RECEIVE for CICS as an HTTP client receives the body of an HTTP response that a server has made. The headers for the HTTP response can be examined separately using the WEB READ HTTPHEADER command or the HTTP header browsing commands. A session token must be included on this command. For guidance on the correct use of the WEB RECEIVE command for CICS as an HTTP client, see "HTTP client requests from a CICS application" in the CICS Internet Guide.

Code page conversion for the incoming message can be specified on this command.

Note: The RTIMOUT value specified for the transaction that starts the user application indicates the time that the application is prepared to wait to receive the incoming message. (RTIMOUT is specified on the transaction profile definition). 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 for applications that are making HTTP client requests.
Tip: For CICS as an HTTP client, the CONVERSE command can be used as an alternative to issuing a WEB SEND command followed by a WEB RECEIVE command.

Options

CLIENTCONV(cvda)
specifies whether or not CICS translates the entity body of the response from the character set used by the server, to a code page suitable for the application. The default is that the entity body is converted.
CLICONVERT
CICS converts the entity body of the response from the character set used by the server, into the code page that you identify for the application.
NOCLICONVERT
CICS does not convert the entity body of the response, and it is passed to the application in the character set used by the server.

You do not need to specify a character set or application code page on the WEB RECEIVE command for CICS as an HTTP client. If code page conversion is required, CICS identifies the character set used by the server by examining the Content-Type header of the message. If the header does not provide this information, or if the named character set is not supported by CICS for code page conversion, the ISO-8859-1 character set is used. For the application's code page, the default code page for the local CICS region (as specified in the LOCALCCSID system initialization parameter) is used, or an alternative EBCDIC code page that you specified on the WEB OPEN COMMAND.

Note that for code page conversion to take place, the media type for the message must specify a type of data content that can be identified as text according to the IANA definitions. For messages where no media type is given but CLICONVERT is specified, code page conversion also takes place. If a non-text media type is present, CICS does not convert the message body.

INTO(data-area)
specifies the buffer that is to contain the data being received.
LENGTH(data-area)
specifies a fullword binary variable which is set to the amount of data that CICS has returned to the application. Note that this might be slightly less than the limit that you set using the MAXLENGTH option, especially if a double-byte or multi-byte character set is involved, because CICS does not return a partial character at the end of the data.
  • If the NOTRUNCATE option is not specified, any further data present in the message has now been discarded. A LENGERR response with a RESP2 value of 57 is returned if further data was present.
  • If the NOTRUNCATE option is specified, any additional data is retained. A LENGERR response with a RESP2 value of 36 is returned if additional data is available. The description for the NOTRUNCATE option tells you what to do in this case.
MAXLENGTH(data-value)
specifies the maximum amount, as a fullword binary value, of data that CICS is to pass to the application. The MAXLENGTH option applies whether the INTO or the SET option is specified for receiving data. 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 chunked message, rather than to each individual chunk. The data is measured after any code page conversion has taken place.

If the length of data exceeds the value specified and the NOTRUNCATE option is not specified, the data is truncated to that value, and the remainder of the data is discarded.

If the length of data exceeds the value specified and the NOTRUNCATE option is specified, CICS retains the remaining data and can use it to satisfy subsequent RECEIVE commands.

MEDIATYPE(data-area)
specifies a 56-character data-area to receive the media type (that is, the type of data content) for the body, for example text/xml. See the CICS Internet Guide for more information about media types.
NOTRUNCATE
specifies that when the data available exceeds the length requested on the MAXLENGTH option, the remaining data is not to be discarded immediately but is to be retained for retrieval by subsequent RECEIVE commands. (If no further RECEIVE commands are issued, the data is discarded during transaction termination.)

A single RECEIVE command using the SET option and without the MAXLENGTH option receives all the remaining data, whatever its length. Alternatively, you can use a series of RECEIVE commands with the NOTRUNCATE option to receive the remaining data in appropriate chunks. Keep issuing the RECEIVE command until you are no longer getting a LENGERR response. Bear in mind that if you receive less than the length requested on the MAXLENGTH option, this does not necessarily indicate the end of the data; this could happen if CICS needs to avoid returning a partial character at the end of the data.

SET(ptr-ref)
specifies a pointer reference that is to be set to the address of data received. The pointer reference is valid until the next receive command or the end of task.
SESSTOKEN(data-value)
specifies the session token, an 8-byte binary value that uniquely identifies a connection between CICS and a server. This value is returned by a WEB OPEN command for CICS as an HTTP client. "Session tokens" in the CICS Internet Guide explains the use of the session token.
STATUSCODE(data-value)
specifies a data-area to receive the HTTP status code sent by the server. The code is a binary halfword value. Examples are 200 (normal) or 404 (not found). Receiving the status code is optional, but you should always receive and check the status code in the following circumstances:
  • If you intend to make an identical request to the server, now or during a future connection.
  • If you intend to make further requests to the server using this connection.
  • If your application is carrying out any further processing that depends on the information you receive in the response.
The CICS Internet Guide has basic guidance on appropriate actions for an application to take in response to the status codes for HTTP/1.1.
STATUSTEXT(data-area)
specifies a data-area to receive any text returned by the server to describe the status code. The text is known as a reason phrase. Examples are "OK" (accompanying a 200 status code), or "Bad Request" (accompanying a 400 status code). The STATUSLEN option gives the length allowed for the text.
STATUSLEN(data-value)
specifies, as a fullword binary value, the length of the data-area to receive any text returned by the server to describe the status code (the STATUSTEXT option). The text is known as a reason phrase. Most reason phrases recommended for HTTP are short, but a data-area length of 256 characters is suggested here, in case the server replaces the recommended reason phrase with more detailed information.

Conditions

NOTOPEN
RESP2 values are:
27
Invalid session token.
INVREQ
RESP2 values are:
10
Invalid response header.
15
Code page conversion failure.
22
Invalid chunk received.
41
The connection has been closed.
46
The CLIENTCONV option is invalid.
67
HTTP error in response.
68
Message send with chunked transfer-coding is in progress.
71
Chunked transfer-coding error.
LENGERR
RESP2 values are:
16
Invalid MAXLENGTH.
36
Partial response body returned. Use additional RECEIVEs to obtain remainder.
57
The response body exceeds the length specified, and the remainder of the body has been discarded.
58
The status text exceeds the length specified and has been truncated.
59
The STATUSLEN option value was not greater than zero.
IOERR
RESP2 values are:
42
Socket error.
TIMEDOUT
RESP2 values are:
62
Timeout on socket receive.
End of change