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

WEB OPEN
>>-WEB--OPEN---------------------------------------------------->
>--+-URIMAP(data-value)-------------------------------------------------------------+-->
'-HOST(data-value)--HOSTLENGTH(data-value)--PORTNUMBER(data-value)--SCHEME(cvda)-'
>--+-------------------------+---------------------------------->
'-CERTIFICATE(data-value)-'
>--+---------------------------------------------+-------------->
'-CIPHERS(data-value)--NUMCIPHERS(data-value)-'
>--+----------------------+--SESSTOKEN(data-area)--------------->
'-CODEPAGE(data-value)-'
>--HTTPVNUM(data-area)--HTTPRNUM(data-area)--------------------><
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. The host name and scheme can be used from a preset
URIMAP definition, which also supplies a default path for requests.
When
the connection is open, the application program can make HTTP client requests
to the server and receive responses from it. CICS queries the HTTP version of the server
(using an OPTIONS request) when the connection is opened, and uses this information
for subsequent communications. CICS also returns the HTTP version information
to the application program, to be checked if you plan to write HTTP headers
or send chunked information.
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 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 only relevant when SCHEME(HTTPS) is specified.
If SCHEME(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. "Building
a key ring" in the CICS RACF Security Guide tells you how to
do this.
- 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 only relevant when SCHEME(HTTPS)
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. "Cipher
suites" in the CICS RACF Security Guide has more information
about using cipher suite codes.
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 may still specify the CIPHERS
option, and the setting in the URIMAP definition is overridden by any codes
that you specify for this 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.
- HOST(data-value)
- specifies
the host name on the server to which you want to connect. 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 HOST option is not required.
An
IPv4 address can be used as a host name, but IPv6 addresses are not supported.
If
a port number is required, do not include this with the host name, but use
the PORTNUMBER option to specify it.
- 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.
CICS obtains the HTTP version information
when it opens the connection to the server. If the server does not provide
HTTP version information, CICS assumes that it is at HTTP/1.0 level.
If
your application program writes HTTP headers that might be unsuitable for
a server at HTTP/1.0 level, or if you intend to send a chunked message to
the server (which cannot be received by a server at HTTP/1.0 level), your
application program should also consult the HTTP version information.
Note: CICS does
not make any special provision for a server that is below HTTP/1.0 level. CICS behaves
as though these servers were at HTTP/1.0 level, and returns HTTP/1.0 as the
HTTP version.
- 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 only need to specify the
port number 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.
- 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:
- HTTP
- is
the HTTP protocol, without SSL.
- HTTPS
- is
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.
- SESSTOKEN(data-area)
- returns
the session token, an 8-byte binary value that uniquely identifies this connection
between CICS and
a server. It is returned when the connection is opened successfully. The session
token must be used on all CICS WEB commands that relate to this connection. "Session
tokens" in the CICS Internet Guide explains the 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 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. The URIMAP definition must be for CICS as
an HTTP client, with USAGE(CLIENT) specified.
Conditions
- IOERR
- RESP2
values are:
- 38
- Proxy error.
- 42
- Socket error.
- INVREQ
- RESP2
values are:
- 14
- Code page invalid.
- 22
- Invalid chunk received during the initial OPTIONS request.
- 23
- Invalid client certificate.
- 40
- Scheme invalid.
- 41
- Server closed the connection during the initial OPTIONS request.
- 48
- The format of the host option is invalid.
- 63
- URIMAP object disabled.
- 66
- An error occurred in processing for the XWBOPEN exit.
- 67
- HTTP error in response.
96
SSL not supported.
137
All requested cipher codes have been rejected.
- LENGERR
- RESP2
values are:
- 21
- Invalid host length.
- NOTFND
- RESP2
values are:
- 20
- Host name not resolved by name server.
- 39
- Unknown proxy.
- 61
- The URIMAP object specified was not found.
- NOTAUTH
- RESP2
values are:
- 100
- Host name barred by security exit.
- TIMEDOUT
- RESP2
values are:
- 62
- Timeout on socket receive.