Start of change

WEB RECEIVE (Server)

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

Read syntax diagramSkip visual syntax diagram
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:
  1. If the Web client's request has a Content-Type header naming a character set supported by CICS, that character set is used.
  2. 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.
  3. 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.

Start of changeIn 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.End of change

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.
End of change