WEB RECEIVE (Client)
Receive an HTTP response for CICS® as an HTTP client.
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 Making HTTP requests through CICS as an HTTP client.
When receiving the HTTP body into an application buffer (using either the INTO or SET options), WEB RECEIVE allows you to specify the type of code page conversion used for incoming data received by the CICS application program. If you omit all of the code page conversion options (SERVERCONV, CLNTCODEPAGE, CHARACTERSET, HOSTCODEPAGE), no code page conversion takes place.
- a text media type, a CHAR container is created.
- a non-text media type, a BIT container is created.
If a CHAR container is created, the IANA-registered name of the Coded Character Set Identifier (CCSID) for the data's current code page is retrieved from the HTTP request Content-Type header charset. If this information is not provided or not supported by CICS, the default of ISO-8859-1 is assumed.
Options LENGTH, MAXLENGTH, NOTRUNCATE and CLIENTCONV are not permitted when receiving an HTTP body into a named container.
Options
- BODYCHARSET(data-area)
- specifies the character set of the HTTP response body.
- CLIENTCONV(cvda)
- If
you are receiving data into a buffer (and either the INTO or SET option
is specified), this option 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.
There are certain considerations for code page conversion to take place when using buffers (with either the INTO or SET option specified). If you are receiving data into a buffer, and CHARACTERSET and CLICONVERT are not specified, the media type for the message must specify text as the data content type (according to the IANA definitions) for code page conversion to take place. 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.
If you are using the TOCONTAINER option, do not specify the CLIENTCONV option.
- INTO(data-area)
- specifies the buffer that is to contain the data being received. If the INTO parameter is specified, then MAXLENGTH must also be specified, with a value greater than zero (otherwise an INVREQ error with RESP2 16 is returned to the application).
- 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.
If you are using an application buffer to store your HTTP body, the LENGTH option must be specified when the INTO or SET options are used. If you are using a named container to store your HTTP body (and therefore specify the TOCONTAINER option), do not use the LENGTH option.
- 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.
If you are using the TOCONTAINER option, do not specify the MAXLENGTH option.
- MEDIATYPE(data-area)
- specifies the data content of any message body provided, for
example
text/xml. You must specify a 56-byte area for MEDIATYPE. The media type is up to 56 alphanumeric characters, including appropriate punctuation. For more information on media types, see IANA media types and character sets. - 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. 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.
If you are using the TOCONTAINER option, do not specify the NOTRUNCATE option. The entire HTTP body is stored in the named container by the first WEB RECEIVE command.
- 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 explains the use of the session token.
- 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 that is issued using the same session token or until the end of task.
- 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.
HTTP status code reference for CICS web support 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.
- TOCHANNEL(data-value)
- Specifies the name of the channel that the container
belongs to. The name of the channel can consist of up to 16
alphanumeric characters, including appropriate punctuation.
The acceptable characters are A-Z a-z 0-9 $ @ # / % & ? ! : |
" = , ; < > . - and _. Leading and embedded blanks are not
permitted. If the name is less than 16 characters, it is padded
with trailing blanks. If the channel does not exist,
it is created. This new channel remains in scope until the
link level changes. For more information about channel scope,
see The scope of a channel.
If you plan to ship your channels between CICS regions, bear in mind that you should restrict your characters to standard alphanumeric characters (A-Z 0-9 & : = , ; <>. - _) to ensure they are represented in the same way by all EBCDIC code pages.
You can specify the channel name DFHTRANSACTION to use a transaction channel. A transaction channel does not go out of scope when the link level changes: it is always accessible in the transaction. For more information, see Channels and containers.
If the TOCHANNEL option is not specified, then CICS assumes the current channel.
- TOCONTAINER(data-value)
- Specifies the name of the container where the data is placed. The name of the
container can consist of up to 16 alphanumeric characters, including appropriate punctuation. The
acceptable characters are A-Z a-z 0-9 $ @ # / % & ? ! : | " = , ; < > . - and _. Leading and
embedded blanks are not permitted. If the name is less than 16 characters, it is padded with
trailing blanks.
If you plan to ship your containers between CICS regions, bear in mind that you should restrict your characters to standard alphanumeric characters (A-Z 0-9 & : = , ; <>. - _) to ensure they are represented in the same way by all EBCDIC code pages.
Do not use container names starting with "DFH", unless requested to do so by CICS.
The TOCONTAINER option can only be specified on the first WEB RECEIVE command.
Conditions
- 122 CHANNELERR
- RESP2 values are:
- 1
- The name specified by the TOCHANNEL option contains an illegal character or combination of characters.
- 110 CONTAINERERR
- RESP2 values are:
- 1
- The name specified by the TOCONTAINER option contains an illegal character or combination of characters.
- 19 NOTOPEN
- RESP2
values are:
- 27
- Invalid session token.
- 16 INVREQ
- RESP2
values are:
- 10
- Invalid response header.
- 15
- Code page conversion failure.
- 16
- An INTO and MAXLENGTH error has occurred, as a result of one of
the following:
- Both parameters, INTO and MAXLENGTH, are not specified.
- Parameters INTO and MAXLENGTH are both specified, but MAXLENGTH is less than or equal to zero.
- 22
- Invalid chunk received.
- 41
- The connection has been closed. The server may have timed out due to inactivity on this connection.
- 46
- The CLIENTCONV option is invalid.
- 67
- The content of the response does not conform to HTTP format. The error is generated because there is a syntax problem.
- 68
- Message send with chunked transfer-coding is in progress.
- 71
- Chunked transfer-coding error.
- 144
- One or more of the Web command parameters is invalid.
- 145
- Channel was not specified, and there is no current channel.
- 146
- The named container is a read-only container.
- 147
- Internal conversion error.
- 149
- The TOCONTAINER option can only be specified on the first WEB RECEIVE command.
- 157
- The HTTP headers in the response are longer than 4k, and CICS is unable to process this HTTP response. The session is unusable, and a WEB CLOSE command is required.
- 22 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.
- 17 IOERR
- RESP2
values are:
- 42
- Socket error.
- 124 TIMEDOUT
- RESP2
values are:
- 62
- Timeout on socket receive.