Establishes a connection between the client program and a server on a local or remote system.
CONNECT connect-string TO session {TIMEOUT minutes} {SETTING error} [THEN statement(s) | ELSE statement(s)]
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.
The connect-string parameter specifies the protocol to use, the host to which to connect, etc. The available protocols are:
For a Reality process-to-process connection, connect-string must be a string with the following format:
{*PTP*}{system}^{account{,acct-passwd}}^server{,server-passwd}{^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-passwd 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-passwd 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-passwd 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"
For connection to a remote system using raw TCP/IP, connect-string must be a string with the following format:
*TCP*host;port=port{;option}...
where:
*TCP* specifies that this is a raw TCP/IP connection.
host is the IP address or DNS domain name of the system to which to connect.
port is the port on host to which to connect. Some commonly used TCP port numbers are listed in TCP Parameters.
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”
The CONNECT statement is executed by a client program to establish a connection with a server program on a local or remote 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:
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.
Programming in DataBasic contains example programs that use the CONNECT statement.