The Socket object is a coding alternative to using the Janus Sockets $functions. An application written with the Socket object does not need to manage or refer to socket numbers. An instance of a Socket is essentially an object style reference to a Socket number. Both client and server applications may be written using the Socket object.
Note: To use the Socket object, you must have licensed Janus Sockets.
There are some restrictions on the order in which the Socket object methods are used: for example, a socket port must be connected before data is sent using it, and data may not be sent after the FIN indicator is sent. For more information about Janus Sockets programming, see Janus Sockets User Language coding considerations.
Using Socket methods and $Sock_xxx functions
Most of the Socket methods have analogous $functions, and Socket objects may be used in code intermixed with $Sock_xxx functions and socket numbers ("in peaceful coexistence").
In the individual Socket method description pages (see List of Socket methods), if a Socket method is described as equivalent to a $Sock_xxx function, the method has the same argument list as the $funtion, with one exception: the method has no socket number argument, since the socket is implied by the object instance.
To simplify the conversion of existing Janus Sockets code, two transition methods are provided:
- GetSocketNumber gives the socket number for an object instance.
- GetSocketObject creates an object instance for a given socket number.
These transition methods let you gradually convert an existing application to use Socket objects.
Creating and destroying Socket objects
The Socket object constructor, the New method, creates an instance of a Socket object. The object created with New is a reference to a connection to a remote host using a Janus client socket. The ServerSocket method obtains a reference to a Socket object for a server socket.
The following is an example of the New constructor:
%socko is object Socket %socko = New(clientportname, host, port [, ssl])
If the connect 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, here is an error handler that can be used after the New constructor:
If %socko Is Null Then Print 'Error:' And $Statusd Stop End If
Note: An explicit Discard of the Socket object is not permitted. You use the Close method to close the socket and discard the Socket object.
List of Socket methods
The List of Socket methods shows all the class methods.
Here is a code fragment that fetches the Sirius home page using a Socket object. You may want to contrast this with the $function sample in Simple echo of HTTP/HTML.
%socko object Socket %socko = New('HTTPCLIENT', 'www.sirius-software.com', 80) If %socko Is Null Then Print 'Error:' And $STATUSD Stop End If %socko:SendWithLineEnd('GET / HTTP/1.0') %socko:SendWithLineEnd( ) %socko:Set('PRSTOK','AMBIG|0D0A|0A|0D') Repeat While ( %socko:ReceiveAndParse(%s) ) Print %s End Repeat Print %(Socket):Num('RESET') Print %(Socket):ErrInfo('CODE') %socko:Close