Setting Options

[CWI] Section Options

The following options are recognized in the [CWI] section:

Default timeout=seconds

For client CWI conversations, the default timeout to use when waiting to receive a response from the server after sending an HTTP request. This can be overridden by the application or CICS resources.

The value is specified in seconds. The default value is 2147483648, or about 68 years.

Default connect timeout=seconds

For client CWI conversations, the default timeout to use when trying to connect to a web server. This timeout only applies until the TCP conversation has been established. This can be overridden by the application or CICS resources.

The value is specified in seconds. The default value is 30 seconds.

Tracing=integer-value

Enable CWI tracing. Trace messages describe aspects of CWI processing and are written to the Communications Server log.

The value is an integer. 0 disables tracing; larger values enable progressively more-detailed tracing. Currently the largest value that enables any additional messages is 6. The default value is 0 (no tracing).

Relax URL rules=yes|no

For client CWI conversations, allow non-standard characters in URLs for HTTP requests.

By default, the Communications Server imposes restrictions on the path portion of a URL for an HTTP request. This may cause some CICS WEB OPEN commands to fail if the URL contains characters not permitted by Communications Server. The permitted characters are letters, digits, the forward slash, characters allowed in well-formed URL query-strings, and the "unreserved" and "subdelim" characters defined by RFC 3986 section 3.3. Also permitted are canonical UTF-8 multi-byte character sequences, URL hex escape sequences, and square brackets around the host portion of the URL.

If this option is set to yes, only URLs with malformed hex escape or UTF-8 sequences are rejected. The default value is no.

Reconnect if server closes=yes|no

Enable automatic reconnection for client CWI conversations.

Communications Server can attempt to automatically reconnect to the server if necessary before sending a request. This avoids the application getting an error from CICS WEB SEND and having to do another CICS WEB OPEN. This option is disabled by default to more closely emulate the behavior of CWI on the mainframe. The attempt to reopen may not happen under all conditions and is not guaranteed to succeed; it is for application convenience only.

If this option is set to yes, CICS WEB SEND and WEB CONVERSE will attempt to reopen the conversation if necessary. The default value is no.

Log client certificates=yes|no

For CWI servers using TLS (SSL), log information about certificates received by clients.

If this is set to yes, and a client sends a certificate, some information about the certificate will be written to the Communications Server log. The default value is no.

Sleep time=milliseconds

Configure how long to wait between checks for session availability.

The CWI implementation provides thread safety by serializing operations on each CWI session. If a session is currently in use (some CWI operation is in progress), attempts to use that session will be blocked. Communications Server uses a polling mechanism to detect when the session is available. To avoid excessive CPU use ("busy-waiting"), each waiting thread will sleep between checking the session status. Note this is a rare condition and only applies to applications that attempt to use the same CWI session from multiple threads or processes. There is rarely any reason to change this setting.

This setting controls how long the threads sleep between checks, in milliseconds. The default value is 200 milliseconds.

Note: Smaller values can reduce latency but increase CPU load.

Always send options=yes|no

For CWI client conversations, controls whether an HTTP OPTIONS request is always sent after establishing a connection.

Older versions of Enterprise Server CWI always sent an HTTP OPTIONS request to a server after establishing a connection. This let the CWI implementation verify the state of the connection, confirm there was an HTTP server on the other end, and determine the server's HTTP version. This option can be used to disable this behavior.

This information is not required by the CICS WEB OPEN command unless one or both of the return parameters HTTPVNUM and HTTPRNUM is specified. Mainframe CWI does not make the OPTIONS request if neither of those parameters is used on WEB OPEN. When this option is disabled, Enterprise Server CWI emulates the mainframe and uses OPTIONS only if it is required.

The advantage of enabling this option is faster detection of an incorrect or unavailable server, since the error will be returned by WEB OPEN without waiting for a WEB SEND or WEB CONVERSE. The disadvantages are reduced mainframe compatibility, an extra request/response flow with the server, and potential (rare) issues with servers, proxies, or firewalls that do not handle OPTIONS requests correctly.

If this option is set to no, the OPTIONS request will only be sent by CICS WEB OPEN if HTTPVNUM and/or HTTPRNUM is specified. The default value is yes.