Connect to remote using CLSOCK port
Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for $Sock_Conn is the Socket class New method.
$Sock_Conn creates a connection to a remote host using a Janus client socket port.
%num = $Sock_Conn(socketPortName, remoteHost, remotePort, [options])
|%num||An integer socket identifier or an error code.|
|socketPortName||The client socket port name. The socketPortName default is the MASTER port, if any is defined. However, if you omit socketPortName and no MASTER port is defined, the request is canceled.|
|remoteHost||The remote host name or IP address. This argument is optional or may be the null string if the remote host or remote IP address is fully specified on the port definition REMOTE clause. If remoteHost is specified and is not the null string, it must match the remote host specified explicitly or indicated by a pattern on the port definition. If an asterisk (*) was specified for the remote host on the port definition, remoteHost must be specified. The remote host may also be restricted by JANUS CLSOCK ALLOW rules.|
|remotePort||The port number on the remote host to which the socket will connect. If a port number was specified on the REMOTE clause of the port definition, this argument can be either the matching number or -1, or it can be omitted. If an asterisk (*) was specified for the remote port on the port definition, remotePort must be specified. The port number may also be restricted by JANUS CLSOCK ALLOW rules.|
|options||An option string that can be used to invoke socket-specific processing that is not already explicitly specified on the JANUS DEFINE command for the port. The argument string may contain one or two options, selected from the two pairs of alternatives below. If the argument string is omitted, the option defaults depend on the CLSOCK port definition. If the argument string contains an option that conflicts with the port definition, the request is canceled.
$Sock_Conn return values
The number returned from $Sock_Conn is a positive value which is used as the identifier of the successfully connected socket, or otherwise it is an error code as shown below:
|0||Communications was successful.|
|100||The format of the response from the server was invalid.|
|101||A Get operation exceeded its timeout value.|
|102||The connection was closed before the complete response was received.|
|-100||No free socket numbers for user.|
|-101||Remote host name or IP address missing or mismatch with CLSOCK port definition.|
|-102||Remote port number missing or mismatch with CLSOCK port definition.|
|-103||CLSOCK port not defined or not started.|
|-104||All ports on specified CLSOCK port are busy.|
|-105||Insufficient virtual storage.|
|-106||Maximum connections exceeded.|
|-107||Couldn't resolve remote host.|
|-108||Remote port not responding.|
|-109||Already have SOCKPMAX sockets open on this CLSOCK port.|
|-110||SSL/NOSSL setting mismatch.|
|-111||SSL handshake error.|
|-112||Access to CLSOCK port not enabled by ALLOW rule.|
|-149||Other error during connection attempt which prevents establishment of the connection.|
- $Sock_xxx functions that encounter an "unusable" socket can ordinarily be handled by a jump to an ONRESET label, by request cancellation, or by continuation of the request at the next statement with an error return code. $Sock_Conn, however, always continues execution with the next statement. It does not have a socket number argument, and it cannot encounter a reset socket. You must check the error return code: if it is negative and you try to use it in a subsequent $Sock_xxx call, the request will be cancelled at that time.
- When $Sock_Conn detects an error, it also issues an error message to the user. If you want to suppress this, and the APSY facility for suppressing error messages is not appropriate for your application, you can use the $Resetn function to set the MSGCTL user parameter to 4.
- $Sock_Conn initiates a connection to a remote port over a client socket port. If the remote host and port were specified on the client socket port definition, they don't have to be specified in the function call.
In the following example, because the port definition specifies that all client requests on port
SOCKEMwill go to port 80 at host IP address
220.127.116.11, specifying the destination on the function call is superfluous.
%numcontains either a positive number identifying the socket number or a negative number identifying the type of error received during the attempt to establish a new socket connection. A negative number indicates an error condition, and processing is routed to an error-handling subroutine.
JANUS DEFINE SOCKEM * CLSOCK 5 REMOTE 18.104.22.168 80 Begin ... %num = $Sock_Conn('SOCKEM') If %num Lt 0 Then Call PROCESS_SOCKET_ERROR End If ...
In the example below, the port is defined to accept client requests to any remote port. The $Sock_Conn function specifies a connection to the default web port (80) at a well-known satirical news provider.
* Define the client sockets port. JANUS DEFINE SOCKEM * CLSOCK 5 REMOTE * * Begin ... %num = $Sock_Conn('SOCKEM', 'www.theonion.com', 80) If %num Lt 0 Then Call PROCESS_SOCKET_ERROR End If ...
FINCLOSEoption is useful in situations where
FINis as good as
RESETfor rendering a connection unusable, and where it's important to know that
FINhas been sent to avoid wasted processing or even a hung connection.
For example, an appropriate occasion for
FINCLOSEis a Janus Sockets application communicating with a web server that is using a keep-alive facility (multiple requests over the same TCP/IP connection). Such a web server could close the connection between any pair of requests, and probably would use
FINCLOSE, the Janus thread that connected to the web server would remain in-use until the Janus Sockets application tried to receive data on the connection and so noticed the closed connection.