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 SSL. 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. SSL Use SSL over the connection. Setting SSL here is redundant if the port definition includes the SSL parameter but not SSLOPT, and it is invalid if the port definition excludes the SSL parameter. NOSSL Do not use SSL over the connection. This selection is invalid if the port definition includes the SSL parameter but not SSLOPT, and it is redundant if the port definition does not include the SSL parameter.
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 SOCKEM will go to port 80 at host IP address 198.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')

Socket class	List of Socket methods	Socket methods syntax
Notation conventions for methods