$Sock Conn: Difference between revisions

From m204wiki
Jump to navigation Jump to search
(Automatically generated page update)
 
(One intermediate revision by one other user not shown)
Line 1: Line 1:
{{DISPLAYTITLE:$Sock_Conn}}
{{DISPLAYTITLE:$Sock_Conn}}
<span class="pageSubtitle">Connect to remote using CLSOCK port</span>
<span class="pageSubtitle">Connect to remote using CLSOCK port</span>
<p class="warn"><b>Note: </b>Most Sirius $functions have been deprecated in favor of Object Oriented
<p class="warn"><b>Note: </b>Many $functions have been deprecated in favor of Object Oriented
methods. The OO equivalent for <var>$Sock_Conn</var> is the <var>Socket</var> class <var>[[New (Socket constructor)|New]]</var> method.</p>
methods. The OO equivalent for <var>$Sock_Conn</var> is the <var>Socket</var> class <var>[[New (Socket constructor)|New]]</var> method.</p>
[[Category: Janus Sockets $functions]]
[[Category: Janus Sockets $functions]]
Line 43: Line 43:


<table>
<table>
<tr class="head"><th>Code</th><th>Meaning</th></tr>
<tr class="head"><th>Code</th>
<th>Meaning</th></tr>
 
<tr><td>0</td>
<tr><td>0</td>
<td>Communications was successful.</td></tr>  
<td>Communications was successful.</td></tr>  
<tr><td>100</td>  
<tr><td>100</td>  
<td>The format of the response from the server was invalid.</td></tr>  
<td>The format of the response from the server was invalid.</td></tr>  
<tr><td>101</td>  
<tr><td>101</td>  
<td>A <var>Get</var> operation exceeded its [[Timeout (HttpRequest property)|timeout]] value.</td></tr>  
<td>A <var>Get</var> operation exceeded its [[Timeout (HttpRequest property)|timeout]] value.</td></tr>  
<tr><td>102</td>  
<tr><td>102</td>  
<td>The connection was closed before the complete response was received.</td></tr>  
<td>The connection was closed before the complete response was received.</td></tr>  
<tr><td>-100</td>  
<tr><td>-100</td>  
<td>No free socket numbers for user.</td></tr>  
<td>No free socket numbers for user.</td></tr>  
<tr><td>-101</td>  
<tr><td>-101</td>  
<td>Remote host name or IP address missing or mismatch with <var>CLSOCK</var> port definition.</td></tr>  
<td>Remote host name or IP address missing or mismatch with <var>CLSOCK</var> port definition.</td></tr>  
<tr><td>-102</td>  
<tr><td>-102</td>  
<td>Remote port number missing or mismatch with <var>CLSOCK</var> port definition.</td></tr>  
<td>Remote port number missing or mismatch with <var>CLSOCK</var> port definition.</td></tr>  
<tr><td>-103</td>  
<tr><td>-103</td>  
<td><var>CLSOCK</var> port not defined or not started.</td></tr>  
<td><var>CLSOCK</var> port not defined or not started.</td></tr>  
<tr><td>-104</td>  
<tr><td>-104</td>  
<td>All ports on specified <var>CLSOCK</var> port are busy.</td></tr>  
<td>All ports on specified <var>CLSOCK</var> port are busy.</td></tr>  
<tr><td>-105</td>  
<tr><td>-105</td>  
<td>Insufficient virtual storage.</td></tr>  
<td>Insufficient virtual storage.</td></tr>  
<tr><td>-106</td>  
<tr><td>-106</td>  
<td>Maximum connections exceeded.</td></tr>  
<td>Maximum connections exceeded.</td></tr>  
<tr><td>-107</td>  
<tr><td>-107</td>  
<td>Couldn't resolve remote host.</td></tr>  
<td>Couldn't resolve remote host.</td></tr>  
<tr><td>-108</td>  
<tr><td>-108</td>  
<td>Remote port not responding.</td></tr>  
<td>Remote port not responding.</td></tr>  
<tr><td>-109</td>  
<tr><td>-109</td>  
<td>Already have <var>[[SOCKPMAX]]</var> sockets open on this <var>CLSOCK</var> port.</td></tr>  
<td>Already have <var>[[SOCKPMAX]]</var> sockets open on this <var>CLSOCK</var> port.</td></tr>  
<tr><td>-110</td>  
<tr><td>-110</td>  
<td>SSL/NOSSL setting mismatch.</td></tr>  
<td>SSL/NOSSL setting mismatch.</td></tr>  
<tr><td>-111</td>  
<tr><td>-111</td>  
<td>SSL handshake error.</td></tr>  
<td>SSL handshake error.</td></tr>  
<tr><td>-112</td>  
<tr><td>-112</td>  
<td>Access to <var>CLSOCK</var> port not enabled by <var>[[JANUS WEB ALLOW|ALLOW]]</var> rule.</td></tr>  
<td>Access to <var>CLSOCK</var> port not enabled by <var>[[JANUS WEB ALLOW|ALLOW]]</var> rule.</td></tr>  
<tr><td>-149</td>  
<tr><td>-149</td>  
<td>Other error during connection.</td></tr>  
<td>Other error during connection attempt which prevents establishment of the connection.</td></tr>  
</table>
</table>


==Usage notes==
==Usage notes==
<ul>
<ul>
<li>$Sock_xxx functions that encounter an "unusable" socket can ordinarily be handled by a jump to an <var>ONRESET</var> label, by request cancellation, or by continuation of the request at the next statement with an error return code. <var>$Sock_Conn</var>, 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. <li>When <var>$Sock_Conn</var> detects an error, it also issues an error message to the user. If you want to suppress this, and the <var>APSY</var> facility for suppressing error messages is not appropriate for your application, you can use the <var>[[$Resetn]]</var> function to set the <var>MSGCTL</var> user parameter to 4.  
<li>$Sock_xxx functions that encounter an "unusable" socket can ordinarily be handled by a jump to an <var>ONRESET</var> label, by request cancellation, or by continuation of the request at the next statement with an error return code. <var>$Sock_Conn</var>, 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.  
</li>
 
<li>When <var>$Sock_Conn</var> detects an error, it also issues an error message to the user. If you want to suppress this, and the <var>APSY</var> facility for suppressing error messages is not appropriate for your application, you can use the <var>[[$Resetn]]</var> function to set the <var>MSGCTL</var> user parameter to 4. </li>
 
<li><var>$Sock_Conn</var> 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.
<li><var>$Sock_Conn</var> 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 <code>SOCKEM</code> will go to port 80 at host IP address <code>198.242.244.47</code>, specifying the destination on the function call is superfluous. <code>%num</code> 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.  
<p>
In the following example, because the port definition specifies that all client requests on port <code>SOCKEM</code> will go to port 80 at host IP address <code>198.242.244.47</code>, specifying the destination on the function call is superfluous. <code>%num</code> 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. </p>
<p class="code">JANUS DEFINE SOCKEM * CLSOCK 5 REMOTE 198.242.244.47 80  
<p class="code">JANUS DEFINE SOCKEM * CLSOCK 5 REMOTE 198.242.244.47 80  
Begin
Begin
Line 94: Line 118:
       Call PROCESS_SOCKET_ERROR
       Call PROCESS_SOCKET_ERROR
     End If    ... </p>  
     End If    ... </p>  
In the example below, the port is defined to accept client requests to any remote port. The <var>$Sock_Conn</var> function specifies a connection to the default web port (80) at a well-known satirical news provider.  
<p>
In the example below, the port is defined to accept client requests to any remote port. The <var>$Sock_Conn</var> function specifies a connection to the default web port (80) at a well-known satirical news provider. </p>
<p class="code">* Define the client sockets port.  
<p class="code">* Define the client sockets port.  
JANUS DEFINE SOCKEM * CLSOCK 5 REMOTE * *  
JANUS DEFINE SOCKEM * CLSOCK 5 REMOTE * *  
Line 102: Line 127:
     If %num Lt 0 Then
     If %num Lt 0 Then
       Call PROCESS_SOCKET_ERROR
       Call PROCESS_SOCKET_ERROR
     End If    ... </p>  
     End If    ... </p> </li>
 
<li>The <code>FINCLOSE</code> option is useful in situations where <code>FIN</code> is as good as <code>RESET</code> for rendering a connection unusable, and where it's important to know that <code>FIN</code> has been sent to avoid wasted processing or even a hung connection.
<li>The <code>FINCLOSE</code> option is useful in situations where <code>FIN</code> is as good as <code>RESET</code> for rendering a connection unusable, and where it's important to know that <code>FIN</code> has been sent to avoid wasted processing or even a hung connection.
 
<p>
For example, an appropriate occasion for <code>FINCLOSE</code> is a <var class="product">Janus Sockets</var> 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 <code>FIN</code>. Without <code>FINCLOSE</code>, the Janus thread that connected to the web server would remain in-use until the <var class="product">Janus Sockets</var> application tried to receive data on the connection and so noticed the closed connection. </ul>
For example, an appropriate occasion for <code>FINCLOSE</code> is a <var class="product">Janus Sockets</var> 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 <code>FIN</code>. Without <code>FINCLOSE</code>, the Janus thread that connected to the web server would remain in-use until the <var class="product">Janus Sockets</var> application tried to receive data on the connection and so noticed the closed connection. </p></li>
</ul>

Latest revision as of 00:00, 21 September 2018

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.