Connects to and associates a Web service instance with the specified server handle. The current application becomes a client application of the connected Web service.

Return type: LOGICAL

Applies to: Server object handle

Syntax

CONNECT ( [ connection-parms ] )
connection-parms
A character string containing a space-separated list of one or more connection parameters.

The following table describes each Web service connection parameter you can include in this string. This method ignores any other strings included in this parameter.

Table 1. Web service connection parameters
Parameter Description
-Binding binding-name The local name of the binding element contained in the WSDL document. Used in conjunction with -SoapEndpoint. This parameter is optional if the WSDL contains only one binding.
-BindingNamespace binding-namespace The namespace of the binding element within the WSDL document that the application will use. This optional field is needed only if the local binding-name is not unique.
-clientConnectTimeout nMilliseconds The number of milliseconds to wait before timing out each connection attempt.
-connectionLifetime nSeconds The maximum number of seconds that a given connection can be reused for asynchronous requests before it is destroyed. Connections whose lifetime exceeds the specified value are destroyed as they become available. An available connection is one that is not currently reserved to run an asynchronous request.

The default value is 300 seconds.
-maxConnections num-connections Maximum number of connections maintained between the client and the Web Server for asynchronous requests. If num-connections is less than or equal to 0, the application is requesting no predefined limit on the number of connections. If the client application exceeds the specified number of connections, the asynchronous requests are queued.

The default value is 0.
-nohostverify If specified, turns off host verification for an HTTPS Web server connection. Without this parameter specified, the client compares the host name specified in the connection with the Common Name specified in the server certificate, and raises an error if they do not match. With this parameter specified, the client never raises the error. For more information, see Learn about Security and Auditing.
-nosessionreuse If specified, the connection does not reuse the TLS session ID when reconnecting to the same HTTPS-enabled Web server.
-pf filename A text file containing any of the other Web service binding parameters described in this table. If this file contains any other OpenEdge startup parameters, this method ignores them.
-Port port-name The local name of the port element contained within the service element. Used in conjunction with -Service. This parameter is optional if -Service contains only one port.
-servername servername Specifies the server name to be used during the initialization of a TLS connection. This can be used to support Server Name Indication (SNI) .
Note: Server Name Indication (SNI) allows the client to add the hostname that it attempts to connect to during the handshake as a part of the TLS negotiation. It enables the server to select the required domain name and present the certificate with the correct name. It also allows the server to present multiple certificates on the same IP address and TCP port number and thus allows multiple secure (HTTPS) websites (or any other Service over TLS) to be served off the same IP address without requiring all those sites to use the same certificate.
-Service service-name The local name of the service element within the WSDL document that the application will use. This field is optional. Many WSDL documents only support one service and this parameter is optional if there is only one (or zero) service elements defined. Used in conjunction with -Port.
-ServiceNamespace service-namespace The namespace of the service element within the WSDL document that the application will use. Most WSDL documents only support one service and this parameter is optional if there is only one service defined. This parameter is used in conjunction with -Service and is ignored if -Service was not specified. This parameter is optional, if the namespace is included in -Service.
-SOAPEndpoint URL-endpoint The URL identifying the endpoint for this Web service. Used in conjunction with -Binding. It is an error to use this parameter in conjunction with -Service or -Port.
-SOAPEndpointPassword password Optional password to use with the -SoapEndpointUserid. This attribute is ignored if -SoapEndpointUserid is not specified.
-SOAPEndpointUserid user-id Optional user account name to use to connect to a Web service that hosts the Web Server application. If -SOAPEndpointUserid is specified and -SOAPEndpointPassword is not, the AVM uses a blank password.
-sslAuth authentication-type Specifies if access to a SOAP service requires TLS client authentication.

Set this to ssl to enable client authentication for SOAP access. If you set this to basic, the connect method ignores client authentication for SOAP access.
-sslKeyFile filename | target-database The location of the client certificate.

If you do not specify an absolute path of the client certificate file, the connection operation searches the $DLC/keys folder for the client-certificate-file-name.pem file. This option must be set only if -sslAuth parameter is set to ssl.
-sslKeyPwd password The TLS client certificate password in cleartext or in encoded format. For more information on using an encoded format, see Use genpassword to obtain a keystore password-encoded value in Manage OpenEdge Keys and Certificates.
-TargetNamespace targetNamespace The namespace contained in the WSDL document. This parameter can be used as a version check. The information in this parameter is compared against the -TargetNamespace contained in the WSDL document. If they do NOT match, the CONNECT() method fails.
-WSDL wsdl-document The location of the WSDL document. This required parameter is the URL, UNC, or local file path to the WSDL file that describes the Web service. The document can be local or remote. The location can optionally contain a user's account name and password to use when connecting to the Web Server. For more information, see -WSDL parameter security options.

If the protocol is not part of the wsdl-document's URL, the ‘file' protocol is assumed. Additionally, the ‘file' can be a relative pathname as it is relative to the current working directory.

-WSDLAuth authentication-type Specifies if access to a WSDL file requires TLS client authentication.

Set this to ssl to enable client authentication for WSDL access. If you set this to basic, the connect method ignores client authentication for WSDL access.
-WSDLKeyFile filename | target-database The location of the client certificate.

If you do not specify an absolute path of the client certificate file, the connection operation searches the $DLC/keys folder for the client-certificate-file-name.pem file.

This option must be set only if -WSDLAuth parameter is set to ssl.
-WSDLKeyPwd password The TLS client certificate password in cleartext or encoded format. For more information on using an encoded format, see Password encoding in OpenEdge Programming Interfaces.
-WSDLPassword password Optional password to use with -WSDLUserid. This attribute is ignored if -WSDLUserid is not specified.
-WSDLUserid user-id Optional user account name to use in connecting to the Web service that hosts the WSDL document. If -WSDLUserid is specified and -WSDLPassword is not, the AVM uses a blank password.
Note: Connections to an Internet-secure (HTTPS) Web service require the management of public keys on the client (HTTPS client) and private keys on the server (HTTPS server). For an Internet-secure Web service, the HTTPS server is the Web server that hosts the Web service. For information on configuring a Web server for HTTPS, see your Web server documentation. For more information on HTTPS and TLS, and on managing private key and digital certificate stores for OpenEdge TLS clients and servers, see Learn about Security and Auditing.

-WSDL parameter security options

The -WSDL parameter can optionally contain a user account name and password to use to connect to a Web Server.

This is the syntax for specifying the parameter using the HTTP and HTTPS protocols, respectively:

-WSDL http://[user-id[:password]@]
  web-server-host[:web-server-port]WSDL-path
 
-WSDL https://[user-id[:password]@]
  web-server-host[:web-server-port]WSDL-path
user-id
User account name to use to connect to a Web service that hosts the WSDL document. If user-id is specified and password is not, the AVM uses a blank password.
password
Password to use with the user-id. This parameter is ignored if user-id is not specified.
web-server-host
TCP/IP host address of the Web Server that hosts the WSDL document.
web-server-port
TCP/IP port address of the Web Server that host the WSDL document. The default port is 80 for HTTP and 443 for HTTPS.
WSDL-path
URL path to the WSDL document for the Web service.

Instead of building the account name and password into the WSDL string, you can specify the account name using the -WSDLUserid parameter and the password using the -WSDLPassword parameter. If these parameters are used and the WSDL URL (WSDL-path) also contains a user id and password, the information on the WSDL URL is used.

Connection parameter combinations

The CONNECT() method is used to connect an ABL SERVER object to a specific application service. This service can be either an AppServer or a Web service. Independent of the type of application service to which the client is connecting, the client needs to provide the location of the service and transport information. There are two mechanisms for providing this information when connecting to a Web service:

  1. The CONNECT() method can identify a specific service element name and port element name from the WSDL document. The combination of these two element names identify the location of a set of operations that are available on the Web service. It also identifies the transport data. The service element name is specified with the -Service connection parameter and the port element name is specified with the -Port connection parameter.

    If the WSDL document contains several service elements, the CONNECT() method must identify which service element the client wants to connect to, via -Service. If the WSDL document only identifies one service element, the CONNECT() method does not need to contain the service element name. Similarly if the WSDL document (or if the identified service element) only identifies one port element, the CONNECT() method does not need to contain the port element name.

    If the application needs to provide account name and password information, it can accomplish this by providing the account name and password information in the -SoapEndpointUserid and -SoapEndpointPassword parameters.

    If the WSDL document identifies multiple service elements with the same local name, the CONNECT() method must also contain the -ServiceNamespace connection parameter.

  2. If the WSDL document contains several binding elements, the CONNECT() method must identify which binding element the client wants to use, via the -Binding parameter. If the WSDL document only identifies one binding element, the CONNECT() method does not need to contain the binding element name.

    If the application needs to provide account name and password information, it can accomplish this by providing the account name and password information in the -SoapEndpointUserid and -SoapEndpointPassword parameters.

    If the WSDL document identifies multiple binding elements with the same local name, the CONNECT() method must also contain the -BindingNamespace connection parameter.

If an error occurs while executing the CONNECT() method, the method returns FALSE. Otherwise, it returns TRUE. An error can occur if:

  • The server handle is invalid.
  • One of the parameters contains an invalid value.
  • One of the values specified in the connection-parms parameter is invalid.
  • The -TargetNamespace does not match the value contained in the WSDL document.
  • The WSDL document cannot be located.
  • The -WSDLUserid or -WSDLPassword is not valid.

If the CONNECT() method completes successfully, the CONNECTED() method returns TRUE.

The connection lasts until the client application executes the server handle DISCONNECT() method or until the AVM detects any failure condition that automatically terminates the connection.