New (Socket constructor)
Open a new socket (Socket class)
New creates an instance of a Socket object, a connection to a remote host using a Janus
client socket (CLSOCK) port.
The New constructor is similar in effect to $Sock_Conn
and has the same argument list.
Syntax
%socket = [%(Socket):]New[( [[ClientPort=] string], [[Host=] string], - [[Port=] number], [[SSL=] string], - [TcpKeepAlive= boolean])]
Syntax terms
| %socket | A variable that is a reference to a Socket object. | ||||
|---|---|---|---|---|---|
| [%(Socket):] | The optional class name in parentheses denotes a Constructor. See "Usage notes", below, for more information about invoking a Socket Constructor. | ||||
| ClientPort | This optional, name allowed, parameter is the name of the client socket port. The default is the MASTER port, if any is defined. However, if you omit a value for this parameter and no MASTER port is defined, the request is canceled. | ||||
| Host | The name or IP address of the remote host. This argument is optional; if you specify a value, the parameter name, Host (case not important), is allowed as a qualifier.
It may be the null string, if the remote host or remote IP address is fully specified on the port definition REMOTE clause. If hostid 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 (*) is specified for the remote host on the port definition, hostid must be specified. The remote host may also be restricted by JANUS CLSOCK ALLOW rules. | ||||
| Port | The number of the port on the remote host to which the socket will connect. The parameter name, Port (case not important), is allowed as a qualifier.
If a port number is specified on the REMOTE clause of the port definition, the Port value can be the matching number, it can be -1, or it can be omitted. If an asterisk (*) is specified for the remote port on the port definition, a Port value must be specified. The port number may also be restricted by JANUS CLSOCK ALLOW rules. | ||||
| SSL | This name allowed, optional, string argument selects whether SSL encryption is attempted for this socket. The case of the parameter name, Ssl, is not important.
Note: Specifying an argument here is only meaningful when the JANUS DEFINE command for the associated CLSOCK port includes both the SSL and SSLOPT parameters. When both these parameters are set in the port definition, SSL encryption is offered on the connection attempt only if the New method explicitly requests it by setting this parameter to The option 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 Ssl argument, SSL usage depends entirely on the CLSOCK port definition. For more information about Janus SSL support, see the Janus Network Security Reference Manual.
| ||||
| TcpKeepAlive | Setting this name allowed, optional, Boolean value to True lets you generate TCP "keepalives" for a particular (probably client) connection, regardless of the TCPKEEPALIVE parameter setting for the Janus port. Setting TcpKeepAlive to False turns off TCP keepalives even if the port has the TCPKEEPALIVE parameter set.
|
Usage notes
- If the New method connection attempt fails, the object variable is set to
null, and $StatusD is set to what would be the return code value if
the same error had happened with $Sock_Conn, the Janus Sockets $function
that creates a socket connection.
To obtain information about any errors that occur while attempting to construct a Socket object instance, the following error handler can be used after the New constructor:
If %socko Is Null Then Print 'Error:' And $statusd Stop End If
- If the New method 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.
- 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 New call.
In the following example, because the port definition specifies that all client requests on port
SOCKEMwill go to port80at host IP address198.242.244.47, specifying the destination on the function call is superfluous.JANUS DEFINE SOCKEM * CLSOCK 5 REMOTE 198.242.244.47 80 Begin ... %sock = New('SOCKEM') ...
In the example below, the port is defined to accept client requests to any remote port. The New constructor specifies a connection to the default web port (80) at a well-known site.
JANUS DEFINE SOCKEM * CLSOCK 5 REMOTE * * Begin ... %CONN = New('SOCKEM', 'www.amazon.com', 80) ...
- As described in "Using New or other Constructors", New can be invoked with no object, with an explicit class name, or with an object variable in the class, even if that object is Null:
%sock = new %sock = %(Socket):new %sock = %sock:new
- An explicit Discard of the Socket object is not permitted. You use the Close method to close the socket and discard the Socket object.
Examples
If a MASTER CLSOCK port is defined,
a New method invocation does not need to specify a client socket name — the
MASTER CLSOCK port is used by default.
In this circumstance, the following statement would create a
new Socket object and use it to connect to port 80 at afl.com.au:
%socket = new(, 'afl.com.au', 80)
Using the New constructor's named parameters, the previous example becomes:
%socket = new(, host='afl.com.au', port=80)
Using these names to connect to Sirius Software's secure port, and omitting
the initial comma, which the named arguments make optional), gives this:
%socket = new(host='sirius-software.com', port=443, ssl='SSL')