TCPConnect

Syntax

TCPConnect (hostname,service|port[,secure {Default kFalse},verify {Default kTrue}]) Returns socket

Description

Note: The flag is set according to whether Omnis was able to make a call to this external command.

This Web command is multi-threaded, allowing another thread to execute in the multi-threaded server while it runs. Note that the same socket cannot safely be used concurrently by more than one thread.

TCPConnect establishes a TCP/IP connection to a remote application, and returns a new socket representing that connection.

Hostname is an Omnis Character field containing the hostname or IP address of the system on which the remote application is running.

Service/Port is either an Omnis integer field containing the number of the port on which the remote application is listening for new connections, or an Omnis character field containing the name of a service which will be resolved to a port number by a local lookup.

Socket is an Omnis Long Integer field that receives either the number of the new socket, or an error code < 0. Possible error codes are listed in the Web Command Error Codes Appendix.

Secure is an optional Boolean parameter which indicates if a secure connection is required to the server. Pass kTrue for a secure connection, in which case the built-in security technology will be used, so on Windows ‘Secure Channel’ (Schannel) is used, on macOS ‘Secure Transport’ is used, and on Linux OpenSSL is used.

Verify is an optional Boolean parameter which is only significant when Secure is not kFalse. When Verify is kTrue, the command instructs the installed SSL library to verify the server's identity using its certificate; if the verification fails, then the connection will not be established. You can pass Verify as kFalse, to turn off this verification; in this case, the connection will still be encrypted, but there is a chance the server is an impostor. In order to perform the verification, the installed SSL library uses the Certificate Authority Certificates in the cacerts sub-folder of the secure folder in the Omnis folder. If you use your own Certificate Authority to self-sign certificates, you can place its certificate in the cacerts folder, and the installed SSL library will use it after you restart Omnis.

Notes:

This differs from the more standard implementation of the sockets connect call. Instead of creating a socket with one command (such as TCPSocket), then passing the socket to a connect command, TCPConnect creates the socket and returns the socket number in one step.

When using a secure connection all calls to TCPSend are blocking.

Example

# Connect to the server IP address iHostName on port iPort ready for
# sending a message 
Calculate iHostName as  '0.0.0.0'
Calculate iPort as  6000
TCPConnect (iHostName,iPort) Returns iSocket
If  iSocket>0
 # connected 
End If