WEB RECEIVE (Server)
Receive an HTTP request, or a non-HTTP message.
Syntax
Conditions: CHANNELERR, CONTAINERERR, INVREQ, LENGERR, NOTFND
This command is threadsafe.
NOHANDLE, RESP, and
RESP2 are common options that can be added to all EXEC CICS
commands to process error conditions. They are not explicitly included in the command syntax diagram
and option descriptions. For information about these common options and EXEC CICS
command syntax, see EXEC CICS command format and programming considerations.
Description
- The body of an HTTP request that a Web client has made to CICS® as an HTTP server. For guidance on the correct use of the WEB RECEIVE command for this purpose, see Receiving the entity body of an HTTP request .
- A non-HTTP message handled by CICS Web support facilities, with the user-defined (USER) protocol on the TCPIPSERVICE definition. For guidance on non-HTTP messages, see CICS web support and non-HTTP requests .
- A request from another application that has used the CICS business logic interface to contact the application program directly, rather than going through the CICS HTTP listener. For guidance on the CICS business logic interface, see Developing with CICS business logic interface.
The data is returned in its escaped form.
When receiving the HTTP body into an application buffer (using 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 the media type is a text media type, a CHAR container is created.
- If the media type is 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.
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.
CICS receives the body of the server HTTP request into 64-bit (above-the-bar) storage if the HTTP request contains a Content-Length header or is sent as a chunked request. The body is copied into 31-bit (above-the-line) storage only when CICS needs to provide a 31-bit version for the server application.
Options
- BODYCHARSET(data-area)
- Specifies the character set of the HTTP request body.
- 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. HTML coded character sets lists
the IANA character sets that are supported by CICS for code page conversion.
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.
- CLNTCODEPAGE(data-value)
- This option is supported for upgrade purposes only. CHARACTERSET replaces it. The action taken by CICS is the same for both keywords.
- 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.
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.
- INTO(data-area)
- Specifies the buffer that is to contain the data being received. If the HTTP request contains a Content-Length header or was sent in chunks, CICS holds the HTTP body in internal 64-bit storage; otherwise CICS holds the body in internal 31-bit storage. The body is copied from this internal storage to the application buffer that is specified in the INTO option.
If the INTO option is specified, 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
that 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. - 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.
- 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
SRVCONVERT and let CICS determine
a suitable character set and code page.
If you are using the TOCONTAINER option, do not specify the SERVERCONV option.
- SRVCONVERT
- CICS converts the entity body of the message,
before it is passed to the application.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.
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.
If the HTTP request contains a Content-Length header or has been sent in chunks, CICS holds the HTTP body in internal 64-bit storage; otherwise CICS holds the body in internal 31-bit storage. The body is copied from this internal storage into storage that is accessible to the application, and the pointer reference is set to this copy.
- 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.
When TOCONTAINER is specified, CICS holds the received body of the HTTP request in 64-bit storage until the application uses a CONTAINER API command to obtain the HTTP body.
- TYPE(cvda)
- Returns
the type of request received. CVDA values are:
- HTTPYES
- indicates an HTTP request.
- HTTPNO
- indicates a non-HTTP request.
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
- 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.
- 16 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 NOSRVCONVERT.
- 81
- HOSTCODEPAGE cannot be specified with NOSRVCONVERT.
- 84
- Body incomplete.
- 145
- Channel was not specified, and there is no current channel.
- 146
- The named container is a read-only container.
- 147
- Internal conversion error.
- 148
- User protocol is not supported for containers.
- 149
- The TOCONTAINER option can only be specified on the first WEB RECEIVE command.
- 22 LENGERR
- RESP2
values are:
- 16
- The MAXLENGTH option value was less than or equal to 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.
- 13 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.