WEB CONVERSE

Send an HTTP request by CICS® as an HTTP client, and receive a response from the server, using a single command.

Syntax

WEB CONVERSE

Conditions: IOERR, INVREQ, LENGERR, NOTFND, NOTOPEN,

Description

WEB CONVERSE enables an application program to compose and send an HTTP client request, and receive a response from the server. A session token must be included on this command.

The HTTP client request is made using a connection that has been opened using the WEB OPEN command. The WEB CONVERSE command can be used to send the request.
The response from the server is received by CICS Web support and passed to the application. The WEB CONVERSE command can be used to make the application program wait for and receive the HTTP response.

Options sending the HTTP client request

FROM(data-area)

Specifies a buffer of data which holds the message body. The message body is built by the application program. When you specify the FROM option, use the FROMLENGTH option to specify the length of the buffer of data.

FROMLENGTH(data-area)

Specifies the length, as a fullword binary value, of the buffer of data supplied on the FROM option (the message body). It is important to state this value correctly, because an incorrect data length can cause problems for the recipient of the message.

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, but not spaces. CICS checks that the format of the media type is correct, but does not check the validity of the media type against the data content. CICS uses this information to produce the Content-Type header for the message.

For requests that require a body, you must specify the MEDIATYPE option. There is no default.

METHOD(cvda)

Specifies the HTTP method for the request.

The GET, POST, PUT, and DELETE methods are supported by this command. CICS bars the sending of a message body for methods where it is inappropriate, and requires it for methods where it is appropriate.

CVDA values are as follows:

GET

Obtain a resource from the server. A request body is not allowed.

POST

Send data to a server. A request body is required.

PUT

Create or modify a resource on the server. A request body is required.

DELETE

Delete a resource on the server. A request body is not allowed.

PATH(data-area)

Specifies the path information for the specific resource within the server that the application needs to access.

PATHLENGTH(data-value)

Specifies the length of the path, as a fullword binary value. If you are providing path information using the PATH option, you need to specify the PATHLENGTH option. Path length information is returned if you use the WEB PARSE URL command to parse a URL.

QUERYSTRING(data-area)

Specifies a query string that is to be supplied to the server as part of the request. You do not need to include a question mark (?) at the beginning of the query string; if you do not include it, CICS supplies it for you automatically when constructing the request. If you include escaped characters in the query string, CICS passes them to the server in their escaped format.

QUERYSTRLEN(data-value)

Specifies the length of the query string supplied on the QUERYSTRING option, as a fullword binary value.

SESSTOKEN(data-value)

Specifies the session token, an 8-byte binary value that uniquely identifies this connection between CICS and a server. This value is returned by a WEB OPEN command for CICS as an HTTP client.

Options for receiving the server's response

INTO(data-area)

Specifies the buffer that is to contain the data being received.

MEDIATYPE(data-area)

Specifies a 56-character data area to receive the media type (that is, the type of data content) for the body, for example text/xml.

The MEDIATYPE option is used for both the sending and receiving functions of the WEB CONVERSE command.

STATUSCODE(data-area)

Specifies a data area to receive the HTTP status code sent by the server. The code is a binary halfword value. Examples are 200 (normal) or 404 (not found). Receiving the status code is optional, but you should always receive and check the status code in the following circumstances:

If you intend to make an identical request to the server, now or during a future connection.
If you intend to make further requests to the server using this connection.
If your application is carrying out any further processing that depends on the information you receive in the response.

STATUSLEN(data-value)

Specifies, as a fullword binary value, the length of the data area to receive any text returned by the server to describe the status code (the STATUSTEXT option). The text is known as a reason phrase. Most reason phrases recommended for HTTP are short, but a data-area length of 256 characters is suggested here, in case the server replaces the recommended reason phrase with more detailed information.

STATUSTEXT(data-area)

Specifies a data area to receive any text returned by the server to describe the status code. The text is known as a reason phrase. Examples are "OK" (accompanying a 200 status code), or "Bad Request" (accompanying a 400® status code). The STATUSLEN option gives the length allowed for the text.

TOLENGTH(data-area)

Specifies a fullword binary variable that is set to the amount of data that CICS has returned to the application.

Optional(data-area)

Conditions

19 NOTOPEN

RESP2 values:

27: Invalid session token.

16 INVREQ

RESP2 values:

32: Media type invalid.
33: Method does not support a body.
34: Method requires a body.
49: The format of the path option is invalid.
54: The HTTP method is not valid.
76: MEDIATYPE option required.

22 LENGERR

RESP2 values:

5: The PATHLENGTH option value was not greater than zero.
8: The QUERYSTRLEN option value was not greater than zero.
50: The FROMLENGTH option value was not greater than zero.
57: The response body exceeds the length specified, and the remainder of the body has been discarded.
58: The status text exceeds the length specified.
59: The STATUSLEN option value was not greater than zero.

17 IOERR

RESP2 values:

42: Socket error.