View source for New (Socket constructor)

{{Template:Socket:New subtitle}}

<var>New</var> creates an instance of a <var>Socket</var> object, a connection to a remote host using a Janus
client socket (<var>[[JANUS DEFINE#type|CLSOCK]]</var>) port.
The <var>New</var> constructor is similar in effect to <var>[[$Sock_Conn]]</var>
and has the same argument list. 

==Syntax==
{{Template:Socket:New syntax}}

===Syntax terms===
<table class="syntaxTable">
<tr><th>%socket</th>
<td>A variable that is a reference to a <var>Socket</var> object. </td></tr> 

<tr><th><var>[%(Socket):]</var> 
<td>The optional class name in parentheses denotes a <var>[[Notation conventions for methods#Constructors|Constructor]]</var>. See [[#Usage notes|"Usage notes"]], below, for more information about invoking a <var>Socket</var> <var>Constructor</var>.</td></tr>

<tr><th><var>ClientPort</var></th> 
<td>This optional, [[Notation conventions for methods#Named parameters|name allowed]], parameter is the name of the client socket port. The default is the <var>[[MASTER]]</var> port, if any is defined. However, if you omit a value for this parameter and no <var>MASTER</var> port is defined, the request is canceled. </td></tr> 

<tr><th><var>Host</var></th> 
<td>The name or IP address of the remote host. This argument is optional; if you specify a value, the parameter name, <var>Host</var> (case not important), is [[Notation conventions for methods#Named parameters|allowed]] as a qualifier. 
<p>It may be the null string, if the remote host or remote IP address is fully specified on the port definition <var>[[REMOTE]]</var> clause. </p>
<p>If <var class="term">hostid</var> 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 (<tt>*</tt>) is specified for the remote host on the port definition, <var class="term">hostid</var> must be specified. </p>
<p>The remote host may also be restricted by <var>[[JANUS CLSOCK#JANUS CLSOCK ALLOW|JANUS CLSOCK ALLOW]]</var> rules. </p></td></tr>

<tr><th><var>Port</var></th> 
<td>The number of the port on the remote host to which the socket will connect. The parameter name, <var>Port</var> (case not important), is allowed as a qualifier. 
<p>If a port number is specified on the <var>[[REMOTE]]</var> clause of the port definition, the <var class="term">Port</var> value can be the matching number, it can be -1, or it can be omitted. If an asterisk (<tt>*</tt>) is specified for the remote port on the port definition, a <var class="term">Port</var> value must be specified. </p>
<p>The port number may also be restricted by <var>JANUS CLSOCK ALLOW</var> rules. </p></td></tr>

<tr><th><var>SSL</var></th> 
<td>This name allowed, optional, string argument selects whether SSL encryption is attempted for this socket. The case of the parameter name, <var>Ssl</var>, is not important. 
<p><b>Note:</b> Specifying an argument here is only meaningful when the <var>[[JANUS DEFINE]]</var> command for the associated <var>CLSOCK</var> port includes both the <var>[[SSL]]</var> and <var>[[SSLOPT]]</var> parameters. When both these parameters are set in the port definition, SSL encryption is offered on the connection attempt only if the <var>New</var> method explicitly requests it by setting this parameter to <code>SSL</code>. </p>
<p>
The <var class="term">option</var> value may be either of the following, although it must not conflict with the explicit or implicit SSL setting on the port definition. If you omit the <var>Ssl</var> argument, SSL usage depends entirely on the <var>CLSOCK</var> port definition. For more information about Janus SSL support, see the <i>[http://www.sirius-oftware.com/maint/download/jansslr.pdf Janus Network Security Reference Manual]</i>. </p>
<table> 
<tr><th><var>SSL</var> </th>
<td>Use SSL over the connection. Setting <code>SSL</code> here is redundant if the port definition includes the <var>SSL</var> parameter but not <var>SSLOPT</var>, and it is invalid if the port definition excludes the <var>SSL</var> parameter. </td></tr>
<tr><th><var>NOSSL</var>
</th><td>Do not use SSL over the connection. This selection is invalid if the port definition includes the <var>SSL</var> parameter but not <var>SSLOPT</var>, and it is redundant if the port definition does not include the <var>SSL</var> parameter.
</td></tr></table>

<tr><th><var>TcpKeepAlive</var> </th>
<td>Setting this name allowed, optional, <var>[[Boolean enumeration|Boolean]]</var> value to <code>True</code> lets you generate TCP "keepalives" for a particular (probably client) connection, regardless of the <var>[[TCPKEEPALIVE (JANUS DEFINE parameter)|TCPKEEPALIVE]]</var> parameter setting for the Janus port. Setting <var>TcpKeepAlive</var> to <code>False</code> turns off TCP keepalives even if the port has the <var>TCPKEEPALIVE</var> parameter set. 
</td></tr></table>

==Usage notes==
<ul>
<li>If the <var>New</var> method connection attempt fails, the object variable is set to
null, and <var>$Statusd</var> is set to what would be the return code value if
the same error had happened with <var>[[$Sock_Conn]]</var>, the <var class="product">Janus Sockets</var> $function
that creates a socket connection.
<p>
To obtain information about any errors that occur while attempting to construct a <var>Socket</var> object instance,
the following error handler can be used after the <var>New</var> constructor: </p>
<p class="code">If %socko Is Null Then
  Print 'Error:' And $STATUSD
  Stop
End If
</p>
<li>If the New method 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>The New method 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 <var>New</var> call.
<p>
In the following example, because the port definition specifies that
all client requests on port <code>SOCKEM</code> will go to port <code>80</code> at host IP
address <code>198.242.244.47</code>, specifying the destination on the function
call is superfluous. </p>
<p class="code">JANUS DEFINE SOCKEM * CLSOCK 5 REMOTE 198.242.244.47 80
Begin
  ...
  %sock = New('SOCKEM')
  ...
</p>
In the example below, the port is defined to accept client requests to any remote port.
The <var>New</var> constructor specifies a connection to the default web port (80) at a well-known site.
<p class="code">JANUS DEFINE SOCKEM * CLSOCK 5 REMOTE * *
Begin
  ...
  %CONN = New('SOCKEM', 'www.amazon.com', 80)
  ...
</p>
<li>As described in [[Object variables#Using New or other Constructors|"Using New or other Constructors"]], <var>New</var> can be invoked with no object, with an explicit class name, or with an object variable in the class, even if that object is <var>Null</var>:<p class="code">%sock = new

%sock = %(Socket):new

%sock = %sock:new
</p>

<li>An explicit <var>Discard</var> of the <var>Socket</var> object is not permitted.
You use the <var>[[Close (Socket function)|Close]]</var> method to close the socket and discard the <var>Socket</var> object.
</ul>

==Examples==
If a <var>[[MASTER]]</var> <var>CLSOCK</var> port is defined,
a <var>New</var> method invocation does not need to specify a client socket name &mdash; the
<var>MASTER</var> <var>CLSOCK</var> port is used by default.
In this circumstance, the following statement would create a
new <var>Socket</var> object and use it to connect to port 80 at <code>afl.com.au</code>:
<p class="code">%socket = new(, 'afl.com.au', 80)
</p>
<p>
Using the <var>New</var> constructor's named parameters, introduced in <var class="product">Sirmods</var> version 6.7,
the previous example becomes: </p>
<p class="code">%socket = new(, host='afl.com.au', port=80) </p>
<p>
Using these names to connect to Sirius Software's secure port, and omitting
the initial comma, which the named arguments make optional), gives this: </p>
<p class="code">%socket = new(host='sirius-software.com', port=443, ssl='SSL')
</p>

{{Template:Socket:New footer}}