WEB CLOSE

Completes the application's use of a connection to a server for CICS® as an HTTP client.

WEB CLOSE

Read syntax diagramSkip visual syntax diagramWEBCLOSESESSTOKEN( data-value)

Conditions: NOTOPEN

This command is threadsafe.

Description

WEB CLOSE notifies CICS that the application program has finished using a client HTTP connection to a server. The session token represents the application's use of the connection. After the application issues the WEB CLOSE command, the specified session token 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 all interaction with the server and with the response that it sends is complete.

When the application program finishes using a client HTTP connection, CICS might or might not close the connection:
  • If the connection is still open when you issue the WEB CLOSE command, and it was opened using a URIMAP resource that specified connection pooling, CICS does not close the connection. CICS checks the state of the connection and places it in a pool for reuse.
  • If the connection is not suitable for connection pooling when you issue the WEB CLOSE command, because the server or your application program has previously made a request to close the connection, or it was not opened using a suitable URIMAP resource, or it is not in a good state, CICS closes the connection and does not place it in a pool.
  • If you do not issue the WEB CLOSE command, CICS closes the connection at end of task. The closed connection cannot be placed in a pool. To enable connection pooling, your application must issue the WEB CLOSE command.

When you issue the WEB CLOSE command, CICS does not request the server to close the connection. If you are not using connection pooling, and CICS will close the connection after the application program has finished, it is good practice to request the server to close the connection by specifying the CLOSESTATUS(CLOSE) option on the final WEB SEND or WEB CONVERSE command. When this option is specified, CICS writes a Connection: close header on the request, or, for a server at HTTP/1.0 level, omits the Connection: Keep-Alive header. The information in the headers means that the server can close its connection immediately after sending the final response, rather than waiting for any further requests before timing out. If you are using connection pooling, do not specify the CLOSESTATUS(CLOSE) option, because closed connections cannot be pooled.

The connection might be closed at the request of the server before the WEB CLOSE command is issued. If you need to test whether the server has requested closure 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 does request closure of the connection, the data relating to that connection is still kept available within CICS until the WEB CLOSE command is issued. The available data includes the most recent message received from the server, and the parameters used to open the connection (such as the scheme and the host name of the server). When a server has closed the connection, the application program cannot perform the following tasks:
  • Send further requests on that connection, using the WEB SEND or WEB CONVERSE commands.
  • Write HTTP headers, using the WEB WRITE HTTPHEADER command.
However, the application program can still perform the following tasks:
  • Receive a response, using the WEB RECEIVE command.
  • Examine HTTP headers, using the WEB READ HTTPHEADER and HTTP header browsing commands.
  • Extract connection information, using the WEB EXTRACT command.
When the WEB CLOSE command is issued, the data associated with the application's use of the connection is cleared.

Options

SESSTOKEN(data-value)
Specifies the session token, an 8-byte binary value that uniquely identifies an application's use of a client HTTP connection between CICS and a server. This value is returned by a WEB OPEN command for CICS as an HTTP client. When you issue the WEB CLOSE command for the connection identified by the session token, CICS clears the data associated with the application's use of the connection, and makes the session token invalid for further use by the application program. Session tokens explains the use of the session token.

Conditions

19 NOTOPEN
RESP2 values are:
27
Invalid session token.
144
One or more of the Web command parameters is invalid.