Start of change

WEB OPEN

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

Read syntax diagramSkip visual syntax diagram
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.

Start of changeIf 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.End of change

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.
Start of change96End of change
Start of changeSSL not supported.End of change
Start of change137End of change
Start of changeAll requested cipher codes have been rejected.End of change
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.
End of change