Open a connection to a server for CICS® as
an HTTP client.
WEB OPEN
>>-WEB OPEN--+-URIMAP(data-value)-+----------------------------->
'-| Host |-----------'
>--+-------------------------+---------------------------------->
'-CERTIFICATE(data-value)-'
>--+---------------------------------------------+-------------->
'-CIPHERS(data-value)--NUMCIPHERS(data-value)-'
>--+----------------------+--SESSTOKEN(data-area)--------------->
'-CODEPAGE(data-value)-'
>--+------------------------------------------+----------------><
'-HTTPVNUM(data-area)--HTTPRNUM(data-area)-'
Host
|--HOST(data-value)--HOSTLENGTH(data-value)--------------------->
>--PORTNUMBER(data-value)--+--------------+---------------------|
'-SCHEME(cvda)-'
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. You can still specify the
CIPHERS option, and the setting in the URIMAP definition is overridden
by any codes that you specify for this option.
Note: EXEC CICS WEB OPEN does not support the
use of an SSL cipher suite specification file in the CIPHERS option.
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, usually EBCDIC, 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.
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.
- 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 the URIMAP option is specified, do not specify the CERTIFICATE,
HOST, HOSTLENGTH, PORTNUMBER, PORTLENGTH, or SCHEME options. The CIPHERS
and NUMCIPHERS options can be omitted or specified in the command;
if specified, they override these settings in the URIMAP definition. Note: EXEC CICS WEB OPEN does not support the use of an SSL cipher suite specification file
in the CIPHERS option.
The URIMAP definition must be for CICS as an HTTP client, with USAGE(CLIENT) specified.
Conditions
- 17 IOERR
- RESP2 values:
- 38
- Proxy error.
- 42
- SSL socket error. There is an issue with the SSL connectivity. One possible cause of
this response is that the system initialization parameter TCPIP is set to NO,
or defaulted to NO, for this CICS region. Another possible
cause is that there are no matching ciphers for this connection. Check for SSL and cipher connection
messages.
- 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.