$Sock Conn

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.

Syntax

%num = $Sock_Conn(socketPortName, remoteHost, remotePort, [options])

Syntax terms

%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. SSL Use SSL (Secure Sockets Layer) encryption over the connection (see SSL, and see the Janus Network Security Reference Manual). Setting SSL here is meaningful only if the port definition includes the SSL and SSLOPT parameters (in which case, by default, SSL is not used unless the socket connection explicitly requests it). Setting SSL here is redundant if the port definition includes SSL but not SSLOPT, and setting it is invalid if the port definition excludes SSL. NOSSL Do not use SSL over the connection. This setting is valid only if the port definition includes the SSLOPT parameter. FINCLOSE If the remote host closes the connection, even if it does so "cleanly" (that is, with FIN rather than RESET), Janus Sockets closes the connection immediately. This setting avoids wasted processing or even a hung connection in a situation(like a keep-alive facility) where a remote application uses a FIN to close a connection with a request. NOFINCLOSE Do not use FINCLOSE processing for this connection.

$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:

Code	Meaning
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.

Usage notes

• $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 SOCKEM will go to port 80 at host IP address 198.242.244.47, specifying the destination on the function call is superfluous. %num contains 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 198.242.244.47 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 ...

• The FINCLOSE option is useful in situations where FIN is as good as RESET for rendering a connection unusable, and where it's important to know that FIN has been sent to avoid wasted processing or even a hung connection.

  For example, an appropriate occasion for FINCLOSE is 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 FIN. Without 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.