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 HTTP client requests from a CICS application .
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.
Code page conversion is not permitted when receiving
an HTTP body into a named container. If the named container was created
by the user application before the
WEB RECEIVE command
was issued, the container is deleted and recreated. The HTTP request
Content-Type header media type information determines whether the
named container is recreated as a BIT or CHAR container (unless the
CHARACTERSET option is specified, in which case CICS assumes
that the data stored in the container is encoded in the CHARACTERSET
code page). If the media type is:
- a text media type, a CHAR container is created.
- a non-text media type, a BIT container is created.
If the HTTP request does not contain media type information,
the default of text media type is assumed.
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.
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.
Options
- BODYCHARSET(data-area)
- specifies
the character set of the HTTP response body.
- The name of the character set can consist of
up to 40 alphanumeric characters, including appropriate punctuation.
If
the HTTP body is received into an application buffer, the character
set returned is as follows:
- If the INTO or SET option is specified, and the HTTP body is converted, CICS returns
the character set of the HTTP body before conversion.
- If the INTO or SET option is specified, and the HTTP body is not
converted, CICS returns the character set specified in
the Content-Type header. If character set information is not available,
blanks are returned.
If the HTTP body is received into a named container, the
character set returned is as follows:
- If the container is a CHAR container, CICS returns
the character set of the encoded data.
- If the container is a BIT container, CICS returns
blanks.
If the value returned is more than 40 bytes, the data
is truncated. If the value returned is less than 40 bytes, the data
is padded to the right with blanks.
- 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.
- 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 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.
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 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.
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.
- 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.