Receive an HTTP request, or a non-HTTP message.

WEB RECEIVE (CICS as an HTTP server)
>>-WEB--RECEIVE--+-INTO(data-area)-+--LENGTH(data-area)--------->
'-SET(ptr-ref)----'
>--+-----------------------+--+------------+--+------------+---->
'-MAXLENGTH(data-value)-' '-NOTRUNCATE-' '-TYPE(cvda)-'
>--+------------------+--+--------------------------+----------->
'-SERVERCONV(cvda)-' +-CHARACTERSET(data-value)-+
'-CLNTCODEPAGE(data-value)-'
>--+--------------------------+--------------------------------><
'-HOSTCODEPAGE(data-value)-'
Conditions: INVREQ, LENGERR, NOTFND
This command is threadsafe.
Description
WEB RECEIVE receives the body
of an HTTP request, or all the data for a non-HTTP message, into an
application-supplied buffer. The headers for an HTTP request can be
examined separately using the WEB HTTPHEADER commands. The item received
by the WEB RECEIVE command can be:
The data is returned in its escaped form. The type of
code page conversion used for incoming data received by the CICS application
program can be specified on this command. If you omit all of the code
page conversion options (SERVERCONV, CLNTCODEPAGE, CHARACTERSET, HOSTCODEPAGE),
no code page conversion takes place.
Options
- CHARACTERSET(data-value)
- specifies
the character set that was used by the Web client for the entity body
of the received item. The name of the character set can consist of
up to 40 alphanumeric characters, including appropriate punctuation. CICS does
not support all the character sets named by IANA. The CICS Internet
Guide lists the IANA character sets that are supported
by CICS for code page conversion.
When the
CHARACTERSET option is specified, SERVERCONV(SRVCONVERT) is assumed,
so code page conversion of the entity body takes place. As an alternative
to identifying the character set yourself, specifying either SERVERCONV(SRVCONVERT),
or HOSTCODEPAGE, or both, and omitting CHARACTERSET, lets CICS identify
the character set for the message body. The
description for the SERVERCONV option tells you what happens in this
case.
- CLNTCODEPAGE(data-value)
- This
option is supported for migration purposes only. CHARACTERSET replaces
it. The action taken by CICS is the same for both keywords. This means
that code page conversion does take place when CLNTCODEPAGE or HOSTCODEPAGE
is specified, even if the SERVERCONV option is not specified.
- HOSTCODEPAGE(data-value)
- specifies
the 8-character name of the CICS (host) code page used by the
application program, into which the entity body of the received item
should be converted from the character set in which it was received
from the Web client. When the HOSTCODEPAGE option is specified, SERVERCONV(SRVCONVERT)
is assumed, so code page conversion of the entity body takes place.
Specifying either SERVERCONV(SRVCONVERT), or CHARACTERSET, or both,
and omitting HOSTCODEPAGE, lets CICS determine the host code page.
The
default if this option is not specified is the default code page for
the local CICS region, as specified in the LOCALCCSID
system initialization parameter.
- 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.
- 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.
- SERVERCONV(cvda)
- specifies
whether or not CICS translates the entity body of the item
received, from the character set used by the Web client, to a code
page suitable for the application. You can use the CHARACTERSET and
HOSTCODEPAGE options on this command to specify the character set
and code page that are used. If you specify either of these options,
code page conversion (SRVCONVERT) is assumed. Alternatively, you can
omit either or both of these options, specify SERVERCONV(SRVCONVERT)
and let CICS determine a suitable character set and code page.
- SRVCONVERT
- CICS converts
the entity body of the message.
When you specify
SRVCONVERT without CHARACTERSET, CICS identifies
the character set as follows:
- If the Web client's request has a Content-Type header naming a
character set supported by CICS, that character set is used.
- If the Web client's request has no Content-Type header or the
named character set is unsupported, the ISO-8859-1 character set is
used.
- For non-HTTP messages (sent using the USER protocol), the ISO-8859-1
character set is used.
When you specify SRVCONVERT without HOSTCODEPAGE, CICS determines
the host code page as the default code page for the local CICS region,
as specified in the LOCALCCSID system initialization parameter.
If you specify SRVCONVERT alone, 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 SRVCONVERT is specified, code page conversion also takes
place. If a non-text media type is present, CICS does not convert
the message body. However, for compatibility with Web-aware applications
coded in earlier releases, if you specify either of the CHARACTERSET
or HOSTCODEPAGE options or omit the SERVERCONV option, the media type
for the message does not influence code page conversion.
- NOSRVCONVERT
- CICS does
not convert the entity body of the item, and it is passed to the application
in the character set used by the Web client. If you specify NOSRVCONVERT,
you cannot specify the CHARACTERSET or HOSTCODEPAGE options.
- 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.
- TYPE(cvda)
- returns
the type of request received. CVDA values are:
- HTTPYES
- indicates an
HTTP request.
- HTTPNO
- indicates a non-HTTP
request.
In CICS Transaction Server for z/OS, Version 3,
HTTP requests and non-HTTP requests use different protocols, which
are specified on TCPIPSERVICE definitions, and must therefore use
different ports. Non-HTTP requests use the user-defined (USER) protocol.
You might use the TYPE option to distinguish between the request types
if you specify the same user-written application program for responding
to both HTTP and non-HTTP requests.
Conditions
- INVREQ
- RESP2
values are:
- 1
- The command is being issued in a non-CICS Web support application.
- 14
- Invalid code page combination.
- 46
- The SERVERCONV option is invalid.
- 80
- CHARACTERSET cannot be specified with SERVERCONV(NOSRVCONVERT).
- 81
- HOSTCODEPAGE cannot be specified with SERVERCONV(NOSRVCONVERT).
- 84
- Body incomplete.
- LENGERR
- RESP2
values are:
- 1
- The MAXLENGTH option value was not greater than zero.
- 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.
- NOTFND
- RESP2
values are:
- 7
- Code page not found.
- 82
- Client code page (character set) not found.
- 83
- Host code page (for server) not found.