CONNECT Statement
Establishes a connection between the client program and a server on a local or remote system.
Syntax
CONNECT connect-string TO session {TIMEOUT minutes} {SETTING error} [THEN statement(s) | ELSE statement(s)]
Syntax Elements
connect-string
A string with one of the formats described in the section Connect String. This specifies the protocol to use, the host to which to connect, etc.
session A variable in which to return a 'session handle'; that is, a value that identifies the connection.
minutes An expression that evaluates to a timeout in minutes. The ELSE clause is executed if a connect request is not received and a session not established within this time. If the TIMEOUT clause is omitted, the program waits indefinitely for the CONNECT to complete.
error A variable in which to return an error code number if the CONNECT operation fails. If the connection is established successfully, error is set to 0. The error codes and corresponding messages are given in File I/O and IPC Error Codes.
statement(s) One or more DataBasic statements, forming a THEN or ELSE clause (or both). At least one statement must be included. The THEN clause is executed if the CONNECT establishes a connection without error; otherwise, the ELSE clause is executed.
Connect String
The connect-string parameter specifies the protocol to use, the host to which to connect, etc. The available protocols are:
Reality process-to-process (PTP)
For a Reality process-to-process connection, connect-string must be a string with the following format:
{*PTP*}{system}^{account{,acct-password}}^server{,server-password}{^Q}
where:
*PTP* specifies that this is a Reality process-to-process connection (optional).
system is an entry in the ROUTE-FILE
, that identifies the remote system to connect to. The local database is used if this is omitted.
^ represents an attribute mark (character with decimal value 254, typed as CTRL+^). All except the last of these must be included.
account is an account on which a server is to be started. Can be omitted if the server should already be running.
acct-password
is the password for the named account, if one is required, unless the account is the server's default account in which case the acct-password is not required.
server is a command in the named account's MD that executes a server program or the name of a server program already running on the specified system or database. In the latter case, the name of the server program is that specified as its server-id in the ACCEPT statement it executes.
If the server-id specified in the CONNECT statement exists as a user-id on the remote system (the system to which connection is being connected), then the server-id is used as the user-id to log to and its associated user profile is used to validate the connection.
If the server-id is not defined as a user-id, the local user's profile is checked for a network id (net-id). If a net-id is defined then this is used as the user-id. However, the net-id must also be defined as a user-id on the remote system otherwise the connection will fail.
If a net-id is not defined on the local system either, then the user-id used on the remote system defaults to the user-id used to logon the process running the client program.
server-password
is required if the server requires a password.
Q is the character Q. If it is appended after an attribute mark, queues the connect instead of starting a server.
The connect request is queued until an already-running server with the name specified issues an accept.
For example:
"FINANCE":AM:"SALES-ACCOUNT":AM:"ORDER-SERVER"
TCP/IP
For connection to a remote system using raw TCP/IP, with optional Transport Layer Security (TLS), connect-string must be a string with the following format:
*TCP*host;port=port{;true_host=true-host{;true_port=true-port}{;proxy_user=user:password}}{;mstimeout=milliseconds}{;TLS=[none || server]}{;option}...
where:
*TCP* specifies that this is a raw TCP/IP connection.
host is the IP address or DNS domain name of the server; this may be a proxy server, in which case true_host, true_port and (if the proxy server is password-protected) proxy_user parameters are required.
port is the required port on the server; some commonly-used TCP port numbers are listed in TCP Parameters.
true-hostis the IP address or DNS domain name of the target server, if host refers to a proxy server.
true-port is the required port on the target server, if host refers to a proxy server.
user:password
is a proxy server user ID and password (both of which may be Base64 encoded).
milliseconds is a timeout in milliseconds which overrides the TIMEOUT specified in the CONNECT statement (or specifies a timeout if the TIMEOUT clause is omitted).
TLS=none enables encryption of data but suppresses authentication (making it easier to test applications against a local HTTP server).
TLS=server enables server authentication and encryption of data.
option is a name/value pair (separated by an equals sign), specifying an optional parameter to be passed to the host.
For example:
"*TCP*152.114.24.123;port=21;linger=5000"
Operation
The CONNECT statement is executed by a client program to establish a connection with a server program on a local or remote system.
-
For Reality process-to-process connections, the connection is made to the system and account identified by the system and account parameters in the connect-string parameter. If a program, identified by server, is running and has issued an ACCEPT statement to this process, the connection is made. If not, the server is instructed to start the program on the server system.
-
For TCP/IP connections, the connection is made to the system identified by the host parameter. The port used is specified in the port parameter. Connections can be to various kinds of remote system. For example:
-
other Reality systems;
-
web, ftp, telnet and time servers;
-
SMTP and POP3 email servers;
-
networked applications (written in Java, for example);
-
other MultiValue systems that support raw TCP/IP;
-
XML applications;
-
SOAP processes (using XML technology).
-
Note, however, that the CONNECT statement provides only a raw TCP connection. You must implement the protocols needed for communication with these remote systems.
Once a session has been started, either the client or the server can send data, receive data, or terminate the connection.
A program can maintain more than one connection at the same time. Each connection is identified in SEND, RECEIVE, RECWAIT, and DISCONNECT statements by the session handle that is assigned by the CONNECT and ACCEPT statements.
Outgoing Web Services and Secure Sockets Encryption
The DataBasic APIs for outgoing web services use the DataBasic CONNECT statement to make TCP connections to the web. Underpinning the CONNECT statement is the Reality Sockets layer. Together, the CONNECT statement and underlying Reality Sockets layer allow secure sockets encryption of outgoing and incoming data. The security layer has been implemented using the OpenSSL library.
You can enable Transport Layer Security (TLS) on a standard TCP connection by setting the parameter TLS=server in the connection string of the DataBasic CONNECT statement. You must set the correct port number when using this parameter.
Alternatively, setting TLS=none suppresses authentication of the server, making it easier to test applications against a local HTTP server.
When using this feature, a connect string may look like:
"*TCP*www.paypal.com;port=443;so_linger=5000;TLS=server"
Note
If TLS is used through a proxy server, the underlying connection code must handle the proxy interface. Hence the connect string must connect to the proxy server and then specify the required host and port using true_host and true_port parameters. Additionally, if the proxy server is password-protected, the parameter proxy_user=user:password must be used.
For example:
"*TCP*bluecoat1;port=80;true_host=www.paypal.com;
true_port=443;proxy_user=fred:1234;TLS=server"
Examples
Programming in DataBasic contains example programs that use the CONNECT statement.