WEB OPEN

Open a connection to a server for CICS® as an HTTP client.

WEB OPEN

Host

Conditions: IOERR, INVREQ, LENGERR, NOTFND, NOTAUTH, TIMEDOUT

This command is threadsafe.

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.

When you open the connection, you can specify a URIMAP resource that contains the information about the URL for the connection. You can specify this information directly on the WEB OPEN command 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.

For information about creating a URIMAP resource for a client request, see Creating a URIMAP definition for an HTTP request by CICS as an 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.

Note: If the connection request does not complete within the deadlock timeout interval (specified in the DTIMOUT attribute of the TRANSACTION definition for the transaction that starts the user application), CICS returns a TIMEDOUT response to the application. Setting DTIMOUT to NO, or allowing it to default to NO, means that the application is prepared to wait indefinitely.

Options

CERTIFICATE(data-value)

Specifies the label of the X.509 certificate that is to be used as the SSL client certificate during the SSL 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 defined in the key ring for the CICS region user ID is used. The certificate must be stored in a key ring in the external security manager's database. For more information, see Building a key ring.

CIPHERS(data-value)

Specifies a string of up to 56 hexadecimal digits that is interpreted as a list of up to 28 2-digit cipher suite codes. The cipher suite codes are used when SSL is active for the connection, so this option is relevant only when the HTTPS option is specified. They indicate the method of encryption to be used for this connection.

Use the NUMCIPHERS option to specify the number of cipher suite codes in your list. The codes that are available depend on what level of encryption has been specified by the ENCRYPTION system initialization parameter. If you specify any cipher codes that are not in the default list for the active encryption level, they are ignored. For more information on cipher suites, see Cipher suites.

You can specify the URIMAP option to use this information directly from an existing URIMAP definition, in which case the CIPHERS option is not required. URIMAP is the preferred option. You can specify an SSL cipher suite specification file in a URIMAP definition, but this is not supported by the CIPHERS option of EXEC CICS WEB OPEN.

Avoid using the CIPHERS option and the URIMAP option at the same time.

When both the CIPHERS option and the URIMAP option are specified, the cipher suites to be used for the connection are determined as follows:

If the URIMAP definition specifies an SSL cipher suite specification file, this cipher suite specification file is always used.
If the URIMAP definition specifies a hexadecimal value as a list of cipher suite codes, the setting in the URIMAP definition is overridden by the CIPHERS option of EXEC CICS WEB OPEN.

If you omit the CIPHERS option and the URIMAP option, but SSL is active for the connection, the default cipher list for the encryption level for the running system is used.

CODEPAGE(data-value)

Specifies a code page that is suitable for the application program. The code page name can be up to 8 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 for the duration of 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 it to the application.

The standard CICS form of this code page name consists of the code page number (or more generally CCSID) written using 3 to 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 to 65535 as a code page name, even if it is not in the standard form.

HOST(data-value)

Specifies the host name on the server to which you want to connect. You can extract this information from a known URL using the WEB PARSE URL command, or from an existing URIMAP definition using the WEB EXTRACT URIMAP 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 only be pooled 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 host name 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 using a single IP address. See also CICS web support fundamentals: Virtual hosting.

A character host name, IPv4 address, or IPv6 address can represent the host name. If you specify an IPv6 address (or a host name 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 (:) cannot be used in a character host name.

HOSTLENGTH(data-value)

Specifies as a fullword binary value, the length of the host name. This information is returned if you use the WEB PARSE URL command to parse a URL, or it can be extracted from an existing URIMAP definition using the WEB EXTRACT URIMAP command. 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 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, will succeed. Actions dependent on the HTTP version include:

Writing HTTP headers that request an action which 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

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 has been received from the server, you can obtain this information using the WEB EXTRACT command.

NUMCIPHERS(data-value)

Specifies, as a halfword binary value, the number of cipher suite codes that you specified for the CIPHERS option.

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. Port number information can be extracted from a known URL using the WEB PARSE URL command, or from an existing URIMAP definition using the WEB EXTRACT URIMAP 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 only be pooled 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 to be 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: The HTTPS protocol, which is HTTP with SSL. If HTTPS is used, the CICS address space must be enabled for SSL.

This information can be extracted from a known URL using the WEB PARSE URL command, or from an existing URIMAP definition using the WEB EXTRACT URIMAP 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 server. The session token must be used on all CICS WEB commands that relate to this connection. See Session tokens for information 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 to be used for the connection to the server.
The host name 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 relating 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 using the URIMAP resource. Connection pooling is enabled when you specify an expiry period in the URIMAP definition using the SOCKETCLOSE attribute, and name the URIMAP resource on the WEB OPEN command.
The label of the X.509 certificate that is to be used as the SSL client certificate, if required.
The cipher suite codes that can be used for the connection.
If you want to use an SSL cipher suite specification file, you must use a URIMAP definition for the connection. EXEC CICS WEB OPEN does not support the use of a cipher suite specification file in the CIPHERS option.

If the URIMAP option is specified, do not specify the CERTIFICATE, HOST, HOSTLENGTH, PORTNUMBER, PORTLENGTH, or SCHEME options.

If the URIMAP option is specified, avoid specifying the CIPHERS option.

When both the CIPHERS option and the URIMAP option are specified, the cipher suites to be used for the connection are determined as follows:

If the URIMAP definition specifies an SSL cipher suite specification file, this cipher suite specification file is always used.
If the URIMAP definition specifies a hexadecimal value as a list of cipher suite codes, the setting in the URIMAP definition is overridden by the CIPHERS option of EXEC CICS WEB OPEN.

The URIMAP definition must be for CICS as an HTTP client, with USAGE(CLIENT) specified.

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 using the OPTIONS method.
23: Incorrect client certificate.
40: Scheme incorrect.
41: Server closed the connection during the initial HTTP request using 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 have been rejected.
138: The port number is greater than 65535.
144: One or more of the Web command parameters is incorrect.

22 LENGERR

RESP2 values:

21: Incorrect host length.

13 NOTFND

RESP2 values:

20: Host name 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: Host name barred by security exit.

124 TIMEDOUT

RESP2 values:

62: Timeout on socket receive.