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

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.