WEB OPEN
Open a connection to an HTTP server for CICS® to act as an HTTP client.
Description
WEB OPEN enables an application program, through CICS web support, to open a connection with a specified host on an HTTP server on the internet. When the connection is open, the application program can make HTTP client requests to the server and receive responses from it.
- 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 codes in the URIMAP resource so that system administrators can manage any changes to these certificates and codes. When using this configuration certificate validation is only done once with the External Security Manager (ESM), rather than per request. This reduces overhead and minimizes the risk of contention for CICS or ESM resources.
- 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 re-enabled in order 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.
For more information about creating a URIMAP resource for a client request, see Creating a URIMAP resource for CICS as a HTTP client.
The WEB OPEN command drives the XWBOPEN user exit, which can make the connection to the server go through a proxy server, if required.
Options
- CERTIFICATE(data-value)
- Specifies the label of the X.509 certificate that is used as the TLS client certificate during the TLS handshake. Certificate labels can consist of up to 32 alphanumeric characters. This option is relevant only when the HTTPS option is specified. If HTTPS is specified, but the CERTIFICATE option is omitted, the default certificate that is defined in the key ring for the CICS region user ID is used. The certificate must be stored in a key ring in the RACF database. For more information, see Building a key ring manually.
- CIPHERS(data-value) - deprecated
- Specifies the
ciphers used for TLS connections. This option is removed for new connections and compilations. For
connections compiled in an earlier release, CIPHERS will operate as documented
for the previous release. For more information, see WEB OPEN documentation for CICS TS 5.6.
If you omit the CIPHERS option and the URIMAP option, but TLS is active for the connection, CICS will use a default list of ciphers. If MAXTLSLEVEL is set to TLS11 or TLS12, then the default cipher list is controlled by feature toggle
com.ibm.cics.web.defaultcipherfile. See Feature toggles. If MAXTLSLEVEL is set to TLS13, then the default cipher list is taken from the defaultciphers.xml file. - CODEPAGE(data-value)
- Specifies a code
page that is suitable for the application program. The code page name can be up to eight
alphanumeric characters. The default is the default code page for the local CICS region, as specified in the LOCALCCSID system
initialization parameter. The code page applies during this connection. When the server returns a
response to an HTTP request, if conversion is requested (which is the default), CICS converts the request body into this code page before passing the request
body to the application.
The standard CICS form of this code page name consists of the code page number (or more generally CCSID) written by using 3 - 5 decimal digits as necessary then padded with trailing spaces to 8 characters. For code page 37, which is fewer than 3 digits, the standard form is 037. CICS also accepts any decimal number of up to 8 digits (padded with trailing spaces) in the range 1 - 65535 as a code page name, even if it is not in the standard form.
- HOST(data-value)
- Specifies the hostname
of the server to which you want to connect. You can extract this information from a known URL by
using the WEB PARSE URL command, or from an existing URIMAP definition by using
the INQUIRE URIMAP SPI command. You can specify the URIMAP
option to use this information directly from an existing URIMAP definition, in which case the
HOST option is not required. Client HTTP connections can be pooled only for
reuse when you specify the URIMAP option; using the HOST
option does not enable connection pooling, even if you extract the information from a URIMAP
definition.
If Transport Layer Security (TLS) is used in the connection to an HTTP server, CICS passes the hostname in the Server Name Indication (SNI) extension during the TLS handshake. This allows CICS to use a TLS communication to a virtual host where the server supports multiple virtual hosts that use a single IP address. See also CICS web support fundamentals: Virtual hosting.
A character hostname, IPv4 address, or IPv6 address can represent the hostname. If you specify an IPv6 address (or a hostname that resolves to an IPv6 address), ensure that you are operating in a dual-mode (IPv4 and IPv6) environment and that the client or server that you are communicating with is also operating in a dual-mode (IPv4 and IPv6) environment.
For more information on IPv6, see Understanding IPv6 and CICS.
You can specify IPv4 and IPv6 addresses in a number of formats. For information on IP addresses, see IP addresses.
If you require a port number, you must not include the port number as part of the HOST option. Use the PORTNUMBER option instead.
Acceptable characters:Alphanumeric characters, hyphens (-), colons (:), or periods (.)
Colons (:) can be used only in the IP address. Colons (:) cannot be used in a character hostname .
- HOSTLENGTH(data-value)
- Specifies the length of the hostname as a fullword binary value. This information is returned if you use the WEB PARSE URL command to parse a URL. You can specify the URIMAP option to use this information directly from an existing URIMAP definition, in which case the HOSTLENGTH option is not required.
- HTTPRNUM(data-area)
- Returns the release number for the HTTP version of the server, as a halfword binary value. (HTTPVNUM returns the version number.) For example, if the server is at HTTP/1.0 level, HTTPRNUM returns 0.
- HTTPVNUM(data-area)
- Returns the
version number for the HTTP version of the server, as a halfword binary value.
(HTTPRNUM returns the release number.) For example, if the server is at
HTTP/1.0 level, HTTPVNUM returns 1.
If you specify the HTTPVNUM and HTTPRNUM options, CICS obtains the HTTP version information when it opens the connection to the server. If the server does not provide HTTP version information in response to this request, or if the version is lower than 1.0, CICS assumes that it is at HTTP/1.0 level.
Specify these options if it is essential for you to check the HTTP version information to confirm whether a planned action by your application, before or during its first request, succeeds. Actions dependent on the HTTP version include:- Writing HTTP headers that request an action that might not be carried out correctly by a server lower than HTTP/1.1 level
- Using HTTP methods that might be unsuitable for servers lower than HTTP/1.1 level
- Using chunked transfer-coding
- Sending a pipelined sequence of requests
The additional HTTP request made by CICS to obtain the HTTP version information has an impact on performance, so do not specify these options if it is not necessary at this stage. When the first response is received from the server, you can obtain this information using the WEB EXTRACT command. To avoid this performance impact, use a URIMAP resource to manage the connection.
- NUMCIPHERS(data-value) - deprecated
- See CIPHERS for details.
- PORTNUMBER(data-value)
- Specifies the port number, as a fullword binary value. You specify the port number only if it is not the default for the specified scheme. For HTTP, the default port number is 80, and for HTTPS, the default port number is 443. You can extract the port number information from a known URL by using the WEB PARSE URL command, or from an existing URIMAP definition by using the INQUIRE URIMAP SPI command. You can specify the URIMAP option to use this information directly from an existing URIMAP definition, in which case the PORTNUMBER option is not required. Client HTTP connections can be pooled only for reuse when you specify the URIMAP option; using the PORTNUMBER option does not enable connection pooling, even if you extract the information from a URIMAP definition.
- SCHEME(cvda)
- Specifies the scheme
that is used for the connection to the server, which can be with or without SSL. CVDA values are as
follows:
- HTTP
- The HTTP protocol, without SSL.
- HTTPS
You can extract this information from a known URL by using the WEB PARSE URL command, or from an existing URIMAP definition by using the INQUIRE URIMAP SPI command. You can specify the URIMAP option to use this information directly from an existing URIMAP definition, in which case the SCHEME option is not required. Client HTTP connections can be pooled for reuse only when you specify the URIMAP option; using the SCHEME option does not enable connection pooling, even if you extract the information from a URIMAP definition.
- SESSTOKEN(data-area)
- Returns the session token, an 8-byte binary value that uniquely identifies this application's use of the connection between CICS and the HTTP server. The session token must be used on all CICS WEB commands that relate to this connection. For more information see Session tokens about use of the session token.
- URIMAP(data-value)
- Specifies the name,
up to 8 characters in mixed case, of a URIMAP definition that provides the following information:
- The scheme that is used for the connection to the server.
- The hostname on the server to which you want to connect.
- A port number, if required.
- A path component for the URI, representing the resource on the server that you want to access. This path becomes the default path for WEB SEND or WEB CONVERSE commands that relate to this connection, but it can be overridden by specifying another path on the WEB SEND or WEB CONVERSE command.
- The expiry period for pooled connections that are opened that use the URIMAP resource. Connection pooling is enabled when you specify an expiry period in the URIMAP definition that uses the SOCKETCLOSE attribute, and name the URIMAP resource on the WEB OPEN command.
- The label of the X.509 certificate that is used as the TLS client certificate, if required.
- The cipher suite codes that can be used for the connection.
The URIMAP definition must be for CICS as an HTTP client, with USAGE(CLIENT) specified.
Note: If the URIMAP option is specified, do not specify the CERTIFICATE, HOST, HOSTLENGTH, PORTNUMBER, PORTLENGTH, or SCHEME options.
Conditions
- 17 IOERR
- RESP2
values:
- 38
- Proxy error.
- 42
- Socket error. There is a connectivity issue.
- 16 INVREQ
- RESP2
values:
- 14
- Code page incorrect.
- 22
- Incorrect chunk received during the initial HTTP request that uses the OPTIONS method.
- 23
- Incorrect client certificate.
- 40
- Scheme incorrect.
- 41
- Server closed the connection during the initial HTTP request that uses the OPTIONS method.
- 48
- The format of the host option is incorrect.
- 63
- URIMAP object is not available.
- 66
- An error occurred in processing for the XWBOPEN exit.
- 67
- The content of the response does not conform to HTTP format. The error is generated because there is a syntax problem.
- 96
- SSL not supported.
- 137
- All requested cipher codes are rejected.
- 138
- The port number is greater than 65535.
- 144
- One or more of the web command parameters is incorrect.
- 158
- defaultciphers.xml was required to provide a default cipher list. The file either does not exist or does not contain a TLS 1.3 cipher. Message DFHWB0112 would have been issued during initialization indicating a problem with the defaultciphers.xml file.
- 22 LENGERR
- RESP2
values:
- 21
- Incorrect host length.
- 13 NOTFND
- RESP2
values:
- 20
- Hostname is not resolved by name server or the format of the host option is incorrect.
- 39
- Unknown proxy.
- 61
- The URIMAP object specified was not found.
- 70 NOTAUTH
- RESP2
values:
- 100
- Hostname barred by security exit.
- 124 TIMEDOUT
- RESP2
values:
- 62
- Timeout on socket receive.