Making HTTP requests through CICS as an HTTP client

HTTP client requests made from XCICS to a server on the Internet are initiated by a user-written application program. This topic tells you how to write an application program that makes an HTTP client request.

For XCICS as an HTTP client, the application program makes requests to a server, and waits for the responses. An application program can control more than one connection, using a session token to differentiate between them.

To make HTTP requests and receive responses, write your application program to follow this process:

If required, produce an entity body, or message body, which is the content of the HTTP request. For many request methods, an entity body is not used, but for the POST and PUT methods (which are used to supply data to the server) it is required. The entity body is formed from an XCICS document (which is created using the EXEC CICS DOCUMENT application programming interface) or from a buffer of data supplied by the application program.

If further requests and responses are wanted, repeat the process. If the server supports persistent connections, and does not close the
connection, there is no need to open a new connection. You can continue using the same session token. If the server closes the connection, you need to issue the WEB OPEN command again if you want to make further requests.

When making an HTTP client request in XCICS Web support, you must open a connection to the server before sending the first request. XCICS returns a session token that represents the connection.

Specify the host name of the server, the length of the host name, and the scheme that is to be used (HTTP or HTTPS). Also specify the port number for the host if this is other than the default for the specified scheme. You can specify the URIMAP option on the WEB OPEN command to use this information directly from an existing URIMAP definition. Alternatively, you can supply the information using the SCHEME, HOST, HOSTLENGTH and PORTNUMBER options. You can extract these details from a known URL using the WEB PARSE URL command, or from an existing URIMAP definition using the WEB EXTRACT URIMAP command.

•	If you need to supply an SSL client certificate, specify the CERTIFICATE option to do this. If you specify the URIMAP option on the WEB OPEN command, you can use this information directly from an existing URIMAP definition.

•

Use the CIPHERS and NUMCIPHERS options to specify a list of cipher suite codes to be used for the connection. If you specify the URIMAP option on the WEB OPEN command, you can either accept the setting from the URIMAP definition, or specify your own list of cipher suite codes to override the URIMAP specification.

For client HTTP requests, XCICS automatically provides the HTTP headers that are required for basic messages, depending on the HTTP protocol version used for the message. You might need to add further HTTP headers to your request.

Write additional HTTP headers for a message before you issue the WEB SEND command to send the message. The exception to this rule is if you are writing headers to be sent as trailing headers on a chunked message, in which case the special process mentioned below applies. When writing HTTP headers for a request:

For XCICS 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.

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 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 this is the last request that you want to make to this server, specify CLOSE for the CLOSESTATUS option. XCICS 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.

8.	If you want to use chunked transfer-coding to send the request body as a series of chunks, follow the additional instructions in "Chunked transfer-coding". Note: Chunked transfer-coding is not supported with:

XCICS assembles the request line, HTTP headers and request body, and sends the request to the server.

The WEB RECEIVE command or the WEB CONVERSE command is used to receive the response from the server. (The WEB CONVERSE command combines the functions of the WEB SEND and WEB RECEIVE commands.) The WEB READ HTTPHEADER command or the HTTP header browsing commands are used to examine the headers.

The time that the application is prepared to wait to receive a response is indicated by the "cwi_timeout" region parameter specified on the xcics configuration file. The timeout limit does not apply to reading the headers of the response. When the period specified by cwi_timeout expires, XCICS returns a TIMEDOUT response to the application.

2.	Specify data areas to receive the HTTP status code sent by the server, and any text returned by the server to describe the status code. Note that the data is returned in its unescaped form.

4.	Receive the response body by specifying either the INTO option (for a data buffer), or the SET option (for a pointer reference), and the LENGTH option. The data is returned in its escaped form, and converted into a code page suitable for the application, unless you request otherwise.

If you want to limit the amount of data received from the response body, specify the MAXLENGTH option. If you want to retain, rather than discarding, any data that exceeds this length, specify the NOTRUNCATE option as well. Any remaining data can be obtained using further WEB RECEIVE commands. If the data has been sent using chunked transfer-coding, XCICS assembles the chunks into a single message before passing it to the application, so the MAXLENGTH option applies to the total length of the entity body for the chunked message, rather than to each individual chunk.

Process the server's response and execute the application's business logic. If the response had a "normal" or informational status code, such as 200 (OK), you can process the response as normal. (The status code is received when you issue the WEB RECEIVE command.) If the response had a status code indicating an error or requesting further action, you should carry out alternative processing to account for this.

When XCICS is an HTTP client, the connection between XCICS and the server can be terminated by the server, or by XCICS following a command issued by the application program, or at end of task.

To manage connection closure effectively, the following behavior is recommended:

On the last request that you want to make to the server, specify CLOSE for the CLOSESTATUS option on the WEB SEND or WEB CONVERSE command. XCICS 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. Specifying the CLOSESTATUS option does not have the same range of effects as issuing the WEB CLOSE command.

If you need to test whether the server has requested termination of the connection, use the WEB READ HTTPHEADER command to look for the Connection: close header in the last message from the server. If the server terminates the connection, the application program cannot send any further requests using that connection, but it can receive responses that the server sent before it terminated the connection.

When all the HTTP requests and responses are completed, issue a WEB CLOSE command, specifying the session token. When the connection is closed, the session token that applies to it is no longer valid for use. The session token is required to receive a response from the server and to read the HTTP headers for the response, so the WEB CLOSE command should not be issued until you have completed all interaction with the server and with the last response that it sent. If the application program does not issue a WEB CLOSE command, the connection is closed at end of task.