Receive an HTTP request, or a non-HTTP message.
WEB RECEIVE (CICS as an HTTP server using buffers) >>-WEB--RECEIVE--+-INTO(data-area)-+--LENGTH(data-area)---------> '-SET(ptr-ref)----' >--+-----------------------+--+------------+--+------------+----> '-MAXLENGTH(data-value)-' '-NOTRUNCATE-' '-TYPE(cvda)-' >--+------------------+--+--------------------------+-----------> +-SRVCONVERT-------+ '-CHARACTERSET(data-value)-' +-NOSRVCONVERT-----+ '-SERVERCONV(cvda)-' >--+--------------------------+--+------------------------+-----> '-HOSTCODEPAGE(data-value)-' '-BODYCHARSET(data-area)-' >--+-----------------------+----------------------------------->< '-MEDIATYPE(data-value)-'
WEB RECEIVE (CICS as an HTTP server using containers) >>-WEB--RECEIVE-------------------------------------------------> >----TOCONTAINER(data-value)-+-----------------------+----------> '-TOCHANNEL(data-value)-' >--+------------+--+--------------------------+-----------------> '-TYPE(cvda)-' '-CHARACTERSET(data-value)-' >--+------------------------+--+-----------------------+------->< '-BODYCHARSET(data-area)-' '-MEDIATYPE(data-value)-'
Conditions: CHANNELERR, CONTAINERERR, INVREQ, LENGERR, NOTFND
This command is threadsafe.
The data is returned in its escaped form.
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.
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.
The charset can be overridden by using the CHARACTERSET option. If CHARACTERSET is specified, a CHAR container is created.
Options LENGTH, MAXLENGTH, NOTRUNCATE, SERVERCONV and HOSTCODEPAGE are not permitted when receiving an HTTP body into a named container.
Containers cannot be used to receive messages that are sent over a user protocol socket.
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.
If the HTTP request body is stored in a buffer and the CHARACTERSET option is specified, the SRVCONVERT option is assumed, so code page conversion of the entity body takes place. CICS can identify the character set for the message body, when receiving data into a buffer (using either the INTO or SET options), if you specify SRVCONVERT or HOSTCODEPAGE, or both options (without specifying CHARACTERSET). The description for the SERVERCONV option tells you what happens in this case.
If the HTTP request body is stored in a container and the CHARACTERSET option is specified, CICS assumes that the data stored in the container is encoded in that code page. CHARACTERSET overrides the Content-Type charset of the received data, and sets the CCSID of the container to the specified CHARACTERSET. This means that when the GET CONTAINER command is issued with that container, the data is converted from the CCSID that was set by the CHARACTERSET parameter on the WEB RECEIVE command, to any code page requested by the user.
The standard CICS form of a host code page name consists of the code page number (or more generally CCSID) written using 3 to 5 decimal digits as necessary then padded with trailing spaces to 8 characters. For code page 37, which is fewer than 3 digits, the standard form is 037. CICS also accepts any decimal number of up to 8 digits (padded with trailing spaces) in the range 1 to 65535 as a code page name, even if it is not in the standard form.
If you are receiving data into a buffer (and either the INTO or SET option is specified), then the HOSTCODEPAGE option is specified and SRVCONVERT is assumed, so code page conversion of the entity body takes place. Specifying either 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.
If you are using the TOCONTAINER option, do not specify the HOSTCODEPAGE option.
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.
If you are using the TOCONTAINER option, do not specify the MAXLENGTH option.
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.
If you are using the TOCONTAINER option, do not specify the SERVERCONV option.
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.
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.
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.
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.