Opening a connection to an HTTP server

When you make an HTTP client request in CICS® web support, you must open a connection to the server before sending the first request. CICS returns a session token that represents the connection.

About this task

When you open the connection to the server, you can specify a URIMAP resource that contains the information about the host server and port for the connection. You can code this information directly in your application program instead of using a URIMAP resource. However, using a URIMAP resource has the following advantages:
  • System administrators can manage any changes to the endpoint of the connection, so you do not need to recompile your applications if the URL for your request changes.
  • If you are using TLS, you can specify a TLS client certificate or cipher suite specification file in the URIMAP resource so that system administrators can manage any changes to these certificates and codes.
  • You can choose to make CICS keep the connections that were opened with the URIMAP resource open after use, and place them in a pool for reuse by another application or another instance of the same application. Connection pooling is only available when you specify a URIMAP resource that has the SOCKETCLOSE attribute set. For more information about the performance benefits of connection pooling, see Connection pooling for HTTP client performance.
  • WEB OPEN URIMAP can use cached IP address that is held in the URIMAP after the initial connection was established, for subsequent outbound web requests that use the same URIMAP, thus eliminating unnecessary DNS lookups.

    When the initial connection to the host is successfully established, WEB OPEN updates the URIMAP with the resolved IP address. For subsequent WEB OPEN requests that use the same URIMAP, the resolved IP address that is cached in the URIMAP is used. If a connection that uses the cached IP address fails, WEB OPEN runs a DNS lookup and updates the URIMAP with the IP address upon a successful connection. If you want to reset or remove the cached IP address that is held in the URIMAP, disable and then re-enable the URIMAP to force CICS to run a DNS lookup. If you have multiple URIMAPs that reference the same HOST, then only one of the URIMAPs needs to be disabled and reenabled to reset the cached IP address for all of them.

  • Likewise, WEB OPEN URIMAP can also use cached HTTP information of the host. This is useful when you run WEB OPEN with the HTTPVNUM and HTTPRNUM options and when you issue WEB SEND with the ACTION(EXPECT) or CHUNKING option. The host HTTP version information that CICS obtains when it opens the connection is cached and reused for subsequent outbound requests that use the same URIMAP, which reduces HTTP OPTIONS requests.
  • Certificates are validated a single time when the URIMAP is installed instead of on every WEB OPEN command.
  • Using a URIMAP allows for outbound connection pooling, which reduces the overhead of creating new connections for every WEB OPEN.
Initiate® a connection with the server by issuing a WEB OPEN command.

Procedure

  1. 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 it is not 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 resource. Connection pooling is enabled for the connection when you specify the URIMAP option and name a URIMAP resource that has the SOCKETCLOSE attribute set.
    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 (but note that extracting information from a URIMAP definition does not enable connection pooling).
  2. If required, specify the CODEPAGE option to change the EBCDIC code page for this connection to something other than the default code page for the local CICS region (set by the LOCALCCSID system initialization parameter). This page might be the EBCDIC code page for another national language.
    When the server returns its response, if conversion is specified CICS converts the response body into this code page before passing it to the application.
  3. If you are using the HTTPS scheme, specify appropriate security options:
    1. If you need to supply an TLS client certificate, specify the CERTIFICATE option.
      If you specify the URIMAP option on the WEB OPEN command, you can use this information directly from an existing URIMAP definition.
    2. Specify the URIMAP option on the WEB OPEN command.
      6.1 6.2 If you omit the CIPHERS option and the URIMAP option, but TLS is active for the connection, then the following occurs:
      • If MAXTLSLEVEL is below TLS13, then CICS uses default 2-digit ciphers.
      • If MAXTLSLEVEL is equal to TLS13 or higher, then CICS uses a default list of ciphers that are taken from the defaultciphers.xml file.

      6.3 If you omit the CIPHERS option and the URIMAP option, but TLS is active for the connection, CICS uses a default list of ciphers that are taken from the defaultciphers.xml file.

  4. If your first planned request involves actions that are not supported in all versions of the HTTP protocol, and you want to check the HTTP version of the server to confirm that the actions will work, specify either or both of the HTTPVNUM and HTTPRNUM options to return this information.
    You might need this information if you do not already know the HTTP version of the server, and you want to take actions that depend on the HTTP protocol version; for example:
    • Writing HTTP headers that request an action that might not be carried out correctly by a server below HTTP/1.1 level
    • Using HTTP methods that might be unsuitable for servers below HTTP/1.1 level
    • Using chunked transfer-coding
    • Sending a pipelined sequence of requests
    You do not always have to check the HTTP version of the server. Consult the HTTP specification to which you are working to see whether it is acceptable to attempt the action with a server of the wrong version. For example, some unsuitable HTTP headers might be ignored by the recipient. You might be able to attempt the request without checking, and handle any error response from the server.
    Do not specify the HTTPVNUM and HTTPRNUM options if you do not require this information, because performance is better without these options.
  5. Optional: If you want to make the connection to the server go through a proxy server, or to apply a security policy to a host name, create a user exit program for the XWBOPEN user exit.
    For details see HTTP client open exit XWBOPEN.

Results

If you specified a URIMAP resource with the SOCKETCLOSE attribute set, CICS checks whether a dormant connection is available in the pool, and if so supplies the connection to the application program for reuse. If no dormant connection is available, or if you did not specify a suitable URIMAP resource, CICS opens a new connection to the server. The application program uses a new connection or a reused connection in exactly the same way.

CICS returns a new session token to the application program to represent this application's use of the connection.

What to do next

Save the session token and use it on all subsequent commands that relate to this use of the connection.