%CREATE_SERVER_CONNECTION

Open an xfServer connection

handle = %CREATE_SERVER_CONNECTION(server[, port])

Return value

handle

The memory handle of the connection on which the file will be opened. (D_HANDLE)

Arguments

server

The server name or IP address. (a)

port

(optional) The port number on which the connection will be opened. The default is 2330. (n)

Discussion

%CREATE_SERVER_CONNECTION creates an xfServer connection and returns a handle, which is then used with the SERVERCONNECTION qualifier to the OPEN statement to open a file. This is an alternative to the traditional @server syntax for accessing remote files.

Multiple files can be opened on a single connection. Furthermore, this function enables your application to have multiple connections to a single xfServer machine where the xfServer instances are on different ports.

%CREATE_SERVER_CONNECTION is the preferred method of using connections in a multi-threaded environment. We recommend that you use it instead of S_SERVER_THREAD_INIT, which is deprecated as of Synergy 12.1.1.

This function is available only if -qrntcompat is 12010100 or higher.

See also

Examples

The example below opens localhost on port 2456, sets mychan = 0 to make the runtime generate a channel number automatically, and then passes the handle with the SERVERCONNECTION qualifier. In this way, you can maintain a server connection across OPEN statements (which offers better performance than opening a new connection every time with @server syntax).

begin
  data myhandle,    D_HANDLE
  data mychan,      int
  myhandle = %create_server_connection("localhost",2456)
  mychan = 0
  open(mychan,"I:I","DAT:myfilename.ism",SERVERCONNECTION:myhandle)
  .
  .   <some I/O>
  .
  close mychan
  myhandle = %destroy_server_connection(myhandle)
end