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 SSL, you can specify an SSL client certificate or cipher suite codes 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.
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 SSL 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. Use the CIPHERS and NUMCIPHERS options to specify a list of cipher suite codes 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 cipher suite codes as overrides.
  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.