For CICS® as
an HTTP client, the WEB SEND command or the WEB CONVERSE command can be used
to make a request. The WEB CONVERSE command combines the options available
on the WEB SEND command and the WEB RECEIVE command, so that you can use a
single command to issue a request and receive the response.
You need to specify an HTTP method when making a request. The method
tells the server what to do with your request. HTTP method reference for CICS Web support provides
basic guidance on the different methods that you can use with CICS Web support.
For more detailed guidance, including any requirements that apply to your
use of methods, you should consult the HTTP specification to which you are
working. See The HTTP protocol for more information
about the HTTP specifications. CICS sends your request with HTTP/1.1 given
as the HTTP version.
Write any additional HTTP headers for the request
using the WEB WRITE HTTPHEADER command before making the request, as described
in Writing HTTP headers for a request.
If wanted, the request can be sent in chunks (chunked transfer-coding),
or you can send a pipelined sequence of requests.
The CICS Application
Programming Reference has full reference information and descriptions
of the options available on the WEB
SEND and WEB
CONVERSE commands. When you issue your chosen command:
- Specify the session token for this connection, using the SESSTOKEN
option.
- Specify the HTTP method for the request (OPTIONS, GET, HEAD, POST,
PUT, DELETE, or TRACE). HTTP method reference for CICS Web support has
guidance for the correct use of each of these methods.
- Specify the path information for the resource on the server that
the application needs to access. The default is the path given
in any URIMAP definition that you referenced on the WEB OPEN command for this
connection. You can specify an alternative path by using the URIMAP option
to name another URIMAP definition from which the path can be taken. (The new
URIMAP definition must specify the correct host name for the current connection.)
Alternatively, you can use the PATH and PATHLENGTH options to provide the
path information.
- Specify any query string for your request, using the QUERYSTRING
and QUERYSTRLEN options.
- Specify any entity body for the HTTP request, and its length. HTTP method reference for CICS Web support has
information about where the use of a request body is and is not appropriate.
- For the GET, HEAD, DELETE, and TRACE methods, a request body is inappropriate.
- For the OPTIONS method, a request body is permitted, but the HTTP/1.1
specification does not define any purpose for this body at present.
- For the POST and PUT methods, a request body must be used.
If a request body is required, the body content can be formed
from a CICS document
(using the CICS DOCUMENT
interface and specifying the DOCTOKEN option to identify the document), or
from the contents of a buffer (specifying the FROM option). Producing an entity body for an HTTP message explains how to produce this, and has information about
size limits for the length of the body.
- Specify the media type for any entity body you are providing, using
the MEDIATYPE option. For requests with the POST and PUT methods,
which require a body, you need to specify the MEDIATYPE option. For requests
with other methods, where no body content is provided, the MEDIATYPE option
is not required.
- If code page conversion is not required for the request
body, specify the appropriate conversion option (depending on whether you
are using the WEB SEND command or the WEB CONVERSE command) so that CICS does not
convert the request body. For CICS as an HTTP client, the default setting
is that the request body is converted, unless it has a non-text media type.
- If code page conversion is required, and the default ISO-8859-1
character set is not suitable, specify a character set that is suitable for
the server. ISO-8859-1 should be acceptable for most servers, unless
you know from earlier connections that the server prefers an alternative.
- If you want to use the Expect header to test the server's acceptance
of the request, specify EXPECT for the ACTION option. This setting
makes CICS send
an Expect header along with the request line and headers for the request,
and await a 100-Continue response before sending the message body to the server.
If a response other than 100-Continue is received, CICS informs the application program and
cancels the send. If no response is received after a period of waiting, CICS sends
the message body anyway.
- If this is the last request that you want to make to this server,
specify CLOSE for the CLOSESTATUS option. CICS writes a Connection: close header
on the request, or, for a server at HTTP/1.0 level, omits the Connection:
Keep-Alive header. Specifying this option when you make your final request
is good behavior, because the information in the headers means that the server
can close its connection with you immediately after sending the final response,
rather than waiting to see if you send further requests before timing out.
The response from the server is still received and made available to your
application. However, you will not be able to send any further requests to
the server using this connection.
- If you want to use chunked transfer-coding to send the request
body as a series of chunks, follow the additional instructions in Using chunked transfer-coding to send an HTTP request or response.
Note: Chunked transfer-coding is not supported
with:
- Servers below HTTP/1.1.
- The WEB CONVERSE command.
- CICS documents
(the DOCTOKEN option).
- If you want to send a pipelined sequence of requests, follow the
instructions in Sending a pipelined sequence of requests.
CICS assembles
the request line, HTTP headers and request body, and sends the request to
the server.