[ External Interface | The ECLiPSe Built-In Predicates | Reference Manual | Alphabetic Index ]

# remote_connect(?Address, ?Peer, ?InitGoal)

Initiate a remote interface connection

Address
  Address for remote connection (Host/Port or variable)
Peer
  Remote Peer name (atom or variable)
InitGoal
  Initialisation Goal (goal or variable)

## Description

Initiate a remote interface connection and sets up a remote peer Peer. ECLiPSe will listen for a remote connection from another process at the Address. Address can be either a variable, or HostName/Port, where either HostName or Port can be variables. The host name and port number are printed on log_output so that the other process can use them. The other process must be able to form a remote interface connection with ECLiPSe. When the predicate returns, the remote process will have attached to the ECLiPSe session. This predicate will block until the remote connection is established, and the remote side hands over control.

Once the Address is printed by the predicate, this information can then be used on the remote side to establish the remote connection, according to the remote interface connection protocol described in the Embedding and Interfacing manual. Once the connection is established, the optional user initialisation is performed on the ECLiPSe side before any further interactions. This is specified by InitGoal: If InitGoal is not a variable, it gives the goal that will be executed for the initialisation. If InitGoal is a variable, then no user initialisation is done before the two sides can interact. Initially, the remote side has control after the connection, so the predicate will return only when the remote side hands over control. Note that the predicate will not fail even if InitGoal fails or aborts.

If Host and Port are initially not variables, they must be valid for forming a socket connection.

This predicate is implemented by remote_connect_setup/3 and remote_connect_accept/6. These two predicates can be used to implement the remote connection, allowing for more flexibility.

### Modes and Determinism

- remote_connect(?, -, ?) is det
- remote_connect(?, +, ?) is semidet

### Modules

This predicate is sensitive to its module context (tool predicate, see @/2).

### Fail Conditions

Peer is an existing peer name.

### Exceptions

(5) type error
  Host, Port or Peer not of correct type
(141) unimplemented functionality
  The remote protocols of the remote and ECLiPSe sides are incompatible.
(170) system interface error
  Port is not a valid port number

## Examples

    % with the following definition for disconnect/0
    disconnect :- writeln(bye).

    % the following will cause `bye' to be printed when the remote connection
    % is disconnected

    remote_connect(_Address, Peer, set_event_handler(Control, disconnect/0)).

## See Also

remote_disconnect / 1, remote_yield / 1, remote_connect_setup / 3, remote_connect_accept / 6