Janus Sockets $functions
The User Language sockets API is implemented as the Janus Sockets $function set. The Janus SOAP Socket, HTTP Helper, Email, and LDAP objects and methods are alternatives that generalize the Janus Sockets $functions and are designed to be easier to use. These $functions and object methods provide User Language programs with the ability to receive and send using socket ports.
This topic is primarily concerned with how to use the individual $functions, though much of its text applies as well to the Socket object methods that are largely analogous to the $functions.
There are a few restrictions on the order in which the Janus Sockets $functions 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.
Sample programs using $functions are included in Sample Janus Sockets programs and in the JANUS file distributed with this product.
Janus Sockets $function summary
The Janus Sockets SOUL $functions for communicating with remote hosts over TCP/IP are listed below and described individually in sections that follow:
|$Sock_Capture||Change print capture setting|
|$Sock_Cert_Info||Get value of entity in partner's certificate|
|$Sock_Cert_Levels||Get number of levels in partner's certificate|
|$Sock_Close||Terminate sending and receiving of data on, and remove from use, one or all Janus Sockets connection(s)|
|$Sock_Conn||Create connection to remote host using CLSOCK port|
|$Sock_ErrInfo||Get info about last Janus Sockets error|
|$Sock_Info||Get info about socket|
|$Sock_Num||Get selected socket numbers|
|$Sock_OnReset||Set label to handle RESET conditions|
|$Sock_Recv||Receive string based on count|
|$Sock_RecvPrs||Receive parsed string|
|$Sock_SendLn||Send string followed by LINEND|
|$Sock_Set||Change parameter or setting on one or all sockets|
|$Sock_SSL_On||Switch to SSL processing on a socket|
|$Sock_Tran_In||Translate string, from character set of remote, to local internal character set ("EBCDIC")|
|$Sock_Tran_Out||Translate string, from local internal character set ("EBCDIC"), to character set of remote|
|$Sock_URL_Encode||Encode special characters into the URL "% hex hex" format|
|Print operations||In addition to the above list of $functions, data may be sent over a socket as the result of a "print" operation. This is accomplished by the $Sock_Capture function. Note that print operations outside a User Language request can be captured as well, if a capturing socket has the NOCLOSE setting.
For example, the DISPLAY command, and the User Language Print statement and Html statement block are all print operations; if they are invoked while print is captured to one or more sockets, their output lines are sent to the sockets. A print line is sent followed by the socket's current LINEND value, if any. See Print capturing hierarchy and other considerations and Print capturing example.
CALLing Sirius $functions
You can invoke many of the Sirius $functions using a SOUL Call statement instead of assigning the function result to a %variable. For example:
%l = $ListNew $ListAdd(%L, 'Once upon a midnight dreary') $ListAdd(%L, 'As I pondered weak and weary') Call $List_Print(%l)
You can Call such $functions and still test for their return code, if necessary. For example:
Call $List_Print(%l) If $List_Print(%l) Then
This "callability" is an optional approach; it does not replace %variable assignment.
The callable $functions are indicated as such in their individual function descriptions. Typically they are $functions that do more than simply return a value, and the value they return is primarily an indicator of whether the function completed successfully. $ListCnt, for example, is a (non-callable) $function that just returns a value.