Janus Sockets User Language coding considerations - Revision history

JAL: /* See also */

2013-04-25T18:56:01Z

JAL: /* See also */

2013-04-25T18:42:28Z

JAL: /* Janus Sockets and Longstrings */

2013-04-25T18:32:36Z

Janus Sockets and Longstrings

← Older revision		Revision as of 18:32, 25 April 2013
Line 361:		Line 361:
	</ol>		</ol>

			==See also==
			<ul>
			<li>Sample Janus Sockets programs
			</ul>

	[[Category:Janus Sockets]]		[[Category:Janus Sockets]]

JAL at 18:30, 25 April 2013

2013-04-25T18:30:12Z

← Older revision		Revision as of 18:30, 25 April 2013
Line 17:		Line 17:
	functions like web service.		functions like web service.

			===Defining a port===
	Before you can use the [[Janus Sockets $functions]] or [[List of Socket methods\|Socket object methods]]		Before you can use the [[Janus Sockets $functions]] or [[List of Socket methods\|Socket object methods]]
	can be used, you must define a Janus port.		can be used, you must define a Janus port.
Line 48:		Line 49:
	sets of $functions or methods).		sets of $functions or methods).

	==Client ~~versus~~ Server ~~Socket~~ programming==		===Comparing Client and Server socket programming===
	As mentioned above, client and server socket programs are nearly identical.		As mentioned above, client and server socket programs are nearly identical.
	The only differences are:		The only differences are:
Line 55:		Line 56:
	or <var>[[Socket class\|Socket]]</var> object <var>[[New (Socket constructor)\|New]]</var> method.		or <var>[[Socket class\|Socket]]</var> object <var>[[New (Socket constructor)\|New]]</var> method.
	A server socket is already connected when the server <var>[[CMD (JANUS DEFINE parameter)\|CMD]]</var> begins processing.		A server socket is already connected when the server <var>[[CMD (JANUS DEFINE parameter)\|CMD]]</var> begins processing.

	<li>Client and server socket objects are identified by number if using		<li>Client and server socket objects are identified by number if using
	$functions, or by object variables if using <var>Socket</var> object methods.		$functions, or by object variables if using <var>Socket</var> object methods.
Line 62:		Line 64:
	range 2 through ''max'', where ''max'' is the value of the <var>[[SOCKMAX parameter\|SOCKMAX]]</var>		range 2 through ''max'', where ''max'' is the value of the <var>[[SOCKMAX parameter\|SOCKMAX]]</var>
	<var class="product">Model 204</var> system parameter.		<var class="product">Model 204</var> system parameter.

	<li><var>NOCLOSE</var>, the default setting for a server socket, allows the		<li><var>NOCLOSE</var>, the default setting for a server socket, allows the
	socket to stay in use across <var class="product">User Language</var> requests.		socket to stay in use across <var class="product">User Language</var> requests.
Line 67:		Line 70:
	This setting can be changed by specifying <var>CLOSE</var> or <var>NOCLOSE</var> on the <var>[[$Sock_Set]]</var> function		This setting can be changed by specifying <var>CLOSE</var> or <var>NOCLOSE</var> on the <var>[[$Sock_Set]]</var> function
	(but <i>not</i> on the <var>Socket</var> method <var>[[Set (Socket function)\|Set]]</var>).		(but <i>not</i> on the <var>Socket</var> method <var>[[Set (Socket function)\|Set]]</var>).

	<li>Some $function (<var>[[$Sock_Info]]</var> and <var>$Sock_Set</var>) and <var>Socket</var> method (<var>[[Info (Socket function)\|Info]]</var> and <var>Set</var>) parameters are valid only for <var>SRVSOCK</var> ports, and some are valid only for		<li>Some $function (<var>[[$Sock_Info]]</var> and <var>$Sock_Set</var>) and <var>Socket</var> method (<var>[[Info (Socket function)\|Info]]</var> and <var>Set</var>) parameters are valid only for <var>SRVSOCK</var> ports, and some are valid only for
	<var>CLSOCK</var> ports.		<var>CLSOCK</var> ports.

JAL: /* Introduction */

2013-04-25T18:21:25Z

Introduction

← Older revision		Revision as of 18:21, 25 April 2013
Line 17:		Line 17:
	functions like web service.		functions like web service.

	Before the [[Janus Sockets $functions]] or [[List of Socket methods\|Socket object methods]]		Before you can use the [[Janus Sockets $functions]] or [[List of Socket methods\|Socket object methods]]
	can be used, a Janus port ~~must be defined~~.		can be used, you must define a Janus port.
	<var class="product">Janus Sockets</var> applications that originate ''inside'' the <var class="product">Model 204</var>		<var class="product">Janus Sockets</var> applications that originate ''inside'' the <var class="product">Model 204</var>
	~~online~~ require a <var class="product">Janus Sockets</var> client port		Online require a <var class="product">Janus Sockets</var> client port
	(<var>[[JANUS DEFINE#type\|CLSOCK]]</var>) ~~to be defined~~.		(<var>[[JANUS DEFINE#type\|CLSOCK]]</var>).
	Janus applications that will respond to incoming requests		Janus applications that will respond to incoming requests
	require a <var class="product">Janus Sockets</var> server port (<var>[[JANUS DEFINE#type\|SRVSOCK]]</var>) ~~to be defined~~.		require a <var class="product">Janus Sockets</var> server port (<var>[[JANUS DEFINE#type\|SRVSOCK]]</var>).

	This example shows both types of ports; it also shows <var>[[JANUS DOMAIN]]</var> and		This example shows both types of ports; it also shows <var>[[JANUS DOMAIN]]</var> and
Line 43:		Line 43:
	JANUS START SERVEM		JANUS START SERVEM
	</p>		</p>
	Once the port is defined, <var class="product">User Language</var> programs using the <var class="product">Janus Sockets</var>		Once the port is defined, you reference it in <var class="product">User Language</var> programs using the <var class="product">Janus Sockets</var> $functions or object methods.
	$functions or object methods ~~can be run against them~~.		Whether for a client
	~~Beyond the port definition~~, the $function or method ~~usage for client~~		socket application or a server socket application, the way you use $function or method is nearly the same (unlike other Janus products, where the client and server processes use distinct
	~~socket applications are~~ nearly ~~identical to server socket applications~~
	(unlike other Janus products, where the client and server processes use distinct
	sets of $functions or methods).		sets of $functions or methods).

JAL: /* Introduction */

2012-10-10T20:56:15Z

Introduction

← Older revision		Revision as of 20:56, 10 October 2012
Line 10:		Line 10:
	A socket is generic by design and will allow any sort of data to be passed back and forth.		A socket is generic by design and will allow any sort of data to be passed back and forth.
	<var class="product">Janus Sockets</var> simply provides the TCP/IP packet handling, buffering and		<var class="product">Janus Sockets</var> simply provides the TCP/IP packet handling, buffering and
	some translation services, and the User Language application is written to handle whatever comes wrapped in the packet.		some translation services, and the <var class="product">User Language</var> application is written to handle whatever comes wrapped in the packet.
	You could, for example, write a web server using		You could, for example, write a web server using
	<var class="product">Janus Sockets</var>, but the <var class="product">User Language</var> programs would have to		<var class="product">Janus Sockets</var>, but the <var class="product">User Language</var> programs would have to
Line 49:		Line 49:
	(unlike other Janus products, where the client and server processes use distinct		(unlike other Janus products, where the client and server processes use distinct
	sets of $functions or methods).		sets of $functions or methods).

	==Client versus Server Socket programming==		==Client versus Server Socket programming==
	As mentioned above, client and server socket programs are nearly identical.		As mentioned above, client and server socket programs are nearly identical.

JAL2 at 20:28, 14 February 2012

2012-02-14T20:28:58Z

@@ Line 334: / Line 334: @@
 The principal purpose of this distinction is to remind you (if you need to
 set one of these values for an application) whether you may simply use the port definition to set the value.
 [[Category:Janus Sockets]]

JAL2 at 23:52, 13 February 2012

2012-02-13T23:52:15Z

JAL2: Created page with "Other Janus products are implemented with algorithms built in to the `Sirius Mods` to handle the underlying complexity of the incoming and outgoing data...."

2012-02-13T23:17:36Z

Created page with "Other Janus products are implemented with algorithms built in to the <var class="product">Sirius Mods</var> to handle the underlying complexity of the incoming and outgoing data...."

New page

Other Janus products are implemented with algorithms built in to the
<var class="product">Sirius Mods</var> to
handle the underlying complexity of the incoming and outgoing data.
That is, the <var class="product">User Language</var> application is written against well-defined structures, like
row-and-column data for <var class="product">Janus Open Server</var>, or HTTP header or form field
values for <var class="product">Janus Web Server</var>.

<var class="product">Janus Sockets</var> is different.
A socket is generic by design and will allow
any sort of data to be passed back and forth.
<var class="product">Janus Sockets</var> simply provides the TCP/IP packet handling, buffering and
some translation services, and the User Language application is written
to handle whatever comes wrapped in the packet.
You could, for example, write a web server using
<var class="product">Janus Sockets</var>, but the <var class="product">User Language</var> programs would have to
handle all the complexity of the HTTP packets.
As a rule, <var class="product">Janus Sockets</var> is targeted at more specific services, not general
functions like web service.

Before the [[Janus Sockets $functions]] or [[List of Socket methods|Socket object methods]]
can be used, a Janus port must be defined.
<var class="product">Janus Sockets</var> applications that originate ''inside'' the <var class="product">Model 204</var>
online require a <var class="product">Janus Sockets</var> client port
(<var>[[JANUS DEFINE command#type|CLSOCK]]</var>) to be defined.
Janus applications that will respond to incoming requests
require a <var class="product">Janus Sockets</var> server port (<var>[[JANUS DEFINE command#type|SRVSOCK]]) to be defined.

This example shows both types of ports; it also shows <var>[[JANUS DOMAIN]]</var> and
<var>[[JANUS NAMESERVER]]</var> commands, which are only used in IBM's TCP/IP environments:
<p class="code">* Specify the domain:
JANUS DOMAIN sirius-software.com

* Specify the location of the name server:
JANUS NAMESERVER 198.242.244.131

* Define a client sockets port:
JANUS DEFINE SOCKEM * CLSOCK 5 REMOTE * 80

* Define a server sockets port at port 1234:
JANUS DEFINE SERVEM 1234 SRVSOCK 5 CMD SERVPGM

* Make the ports available:
JANUS START SOCKEM
JANUS START SERVEM
</p>
Once the port is defined, <var class="product">User Language</var> programs using the <var class="product">Janus Sockets</var>
$functions or object methods can be run against them.
Beyond the port definition, the $function or method usage for client
socket applications are nearly identical to server socket applications
(unlike other Janus products, where the client and server processes use distinct
sets of $functions or methods).

==Client versus Server Socket programming==
As mentioned above, client and server socket programs are nearly identical.
The only differences are:
<ul>
<li>A client socket must be connected by a "connect" $function
(<var>[[$Sock_Conn]]</var>)
or <var>Socket</var> object <var>[[New (Socket constructor|New]]</var> method.
A server socket is already connected when the server <var>[[CMD (JANUS DEFINE parameter)|CMD]]</var> begins processing.
<li>Client and server socket objects are identified by number if using
$functions, or by object variables if using <var>Socket</var> object methods.
If $functions, the socket number for the server socket is 1; the socket
number for a client socket is returned by the <var>$Sock_Conn</var> function,
as the next unused socket number in the
range 2 through ''max'', where ''max'' is the value of the <var>[[SOCKMAX parameter|SOCKMAX]]</var>
<var class="product">Model 204</var> system parameter.
<li><var>NOCLOSE</var>, the default setting for a server socket, allows the
socket to stay in use across <var class="product">User Language</var> requests.
The default for a client socket is <var>CLOSE</var>.
This setting can be changed by specifying <var>CLOSE</var> or <var>NOCLOSE</var> on the <var>$Sock_Set</var> function
(but <i>not</i> on the <var>Socket</var> method <var>[[Set (Socket function)|Set]]</var>).
<li>Some $function (<var>[[$Sock_Info]]</var> and <var>$Sock_Set</var>) and <var>Socket</var> method (<var>[[Info (Socket function)|Info]]</var> and <var>Set</var>) parameters are valid only for <var>SRVSOCK</var> ports, and some are valid only for
<var>CLSOCK</var> ports.
For example, <var>[[AUDTERM (JANUS DEFINE parameter)|AUDTERM]]</var> is only valid for <var>SRVSOCK</var> ports.
</ul>
Except for these differences,
sending and receiving data and all other operations on client and server sockets are identical.

Note that a <var class="product">User Language</var> program that acts as a socket server application
(that is, which can use socket number 1 or a socket instantiated with the
<var>Socket</var> method <var>[[GetSocketObject (Socket function)|GetSocketObject]]</var>) can also connect to client socket ports,
thus being at the same time a server socket and client socket application.
==Determine if executing as SRVSOCK==
Since socket number 1 is used for the server socket, the following example
shows how an application that might run in multiple contexts can determine
whether it is invoked for a <var>SRVSOCK</var> connection:
<p class="code">Begin
If $word($sock_num, , 1) Eq 1 Then
... <i>UL code executed when running as SRVSOCK</i>
End If
...
</p>

If the application is using <var>Socket</var> methods, the presence of the
<var>[[ServerSocket (Socket function)|ServerSocket]]</var>
method, which obtains a reference to a <var>Socket</var> object for the server socket,
leads to the server socket object variable.

==Socket states: OPEN, RESET, FIN indicator==
When you use a socket for communicating with a remote partner,
the socket can be in one of multiple states, and the state
determines the socket operations that can succeed.
After a socket connection is established, the socket exists,
and the term '''in-use''' appies to such a socket.
The term "socket" is typically equivalent to using the term "in-use socket."

When your application has completed all its work with a socket, it
should invoke the <var>[[$Sock_Close]]</var> function
or the <var>Socket</var> method <var>[[Close (Socket function)|Close]]</var>).
After <var>$Sock_Close</var>, the socket number is no longer in-use; after <var>Close</var>,
the socket connection is closed, and the socket object is discarded.

The states of a socket are fully described by the values returned by
the <var>STAT</var> argument of <var>[[$Sock_Info]]</var>
or by the <var>STAT</var> argument of the <var>[[Info (Socket function)|Info]]</var> method.

When all information about a socket is available, the connection exists,
and most of the socket operations can be accomplished, the socket is
said to be in the <var>OPEN</var> state,
or, more correctly, in one of the <var>OPEN</var> states.

If, after a socket connection is established, the connection is lost but the
socket is still in-use, the socket is said to be in the <var>RESET</var> state.
In this state, much of the information about the socket (for example, the remote
host name and port number) is no longer available, and the only completely
meaningful operation for the socket is <var>$Sock_Close</var> or the <var>Close</var> method.
However, as described in [[#Handling connection errors and RESET sockets|Handling connection errors and RESET sockets]], some operations and some
situations allow you to use a <var>RESET</var> socket's socket number with certain
$Sock_xxx functions, or to use a <var>RESET</var> socket object with certain methods.

As stated above, saying that a socket is <var>OPEN</var> actually refers to a set of socket states.
Among these states, the use of the <var>FIN</var> indicator is significant.
You use the <var>FIN</var> option of the <var>[[$Sock_Send]]</var> and <var>[[$Sock_SendLn]]</var> functions, or of the <var>[[Send (Socket function)|Send]]</var> and <var>[[SendWithLineEnd (Socket function)|SendWithLineEnd]]</var>) methods,
to specify that your application will no longer send any data on the socket.

Similarly, the remote partner on a socket may have sent the <var>FIN</var> indicator.
After your application has received all data on that socket, and then requested
additional data, <var>[[$Sock_Recv]]</var> or <var>[[$Sock_RecvPprs]]</var>,
or the <var>[[Receive (Socket function)|Receive]]</var> and
<var>[[ReceiveAndParse (Socket function)|ReceiveAndParse]]</var>) methods,
will indicate that the <var>FIN</var> indication was received.
In these case, the socket is still <var>OPEN</var>, but it is in one of three states:
<ul>
<li><var>FINS</var> (no more data will be sent)
<li><var>FINR</var> (no more data will be received)
<li><var>FINBOTH</var> (no more data will be sent or received)
</ul>

==Invalid $function or method invocation: request cancelled==
Many <var class="product">Janus Sockets</var> $functions and methods have restrictions about the supplied arguments.
If your <var class="product">User Language</var> program violates these restrictions, the request is cancelled.
Some examples of this are:
<ul>
<li>Most of the <var>$Sock_xxx</var> functions require an in-use socket
number (a value returned by <var>$Sock_Conn</var>, or the special socket number 1 for
the inbound connection on a <var>SRVSOCK</var> port) as the first argument.
If you provide an argument that is not an in-use socket number, the request is cancelled.
<li>Many $functions and methods allow an optional argument string
to control the operation of the $function or method.
For example, <var>$Sock_Send</var> and the <var>Send</var> method allow the options <var>BINARY</var>,
<var>FIN</var>, and other strings.
If you invoke <var>$Sock_Send</var> or <var>Send</var> with an invalid string for its optional argument,
the request is cancelled.

<li><var class="product">Janus Sockets</var> $functions and methods are dependent on the state of a socket
only when the state is <var>FINS</var> or <var>FINBOTH</var>.
After sending the <var>FIN</var> indicator on a socket, invoking
<var>$Sock_Send</var>, <var>$Sock_SendLn</var>, or <code>$Sock_Capture(socket, 'ON')</code> for the socket,
or invoking their counterpart methods <var>Send</var>, <var>SendWithLineEnd</var>,
or <var>[[Capture (Socket function)|Capture]]</var>, is another form of programming error, and the request is cancelled.
</ul>

==Handling connection errors and RESET sockets==
Other than invalid arguments to a <var class="product">Janus Sockets</var> $function or method, which always
cancel the request, there are other situations that are less under the control
of the <var class="product">User Language</var> programmer.

<var>CLSOCK</var> (that is, outbound or active) connections, must be
established using the <var>$Sock_Conn</var> function or the <var>Socket</var> method <var>New</var>.
If the $function is successful, it returns a positive
number (called the socket number or socket identifier), which can be used by the other
<var class="product">Janus Sockets</var> $functions.
If the <var>New</var> method is successful, it returns the positive number one.

A number of situations may prevent <var>$Sock_Conn</var> or <var>New</var> from succeeding:
for example, there may not be a <var>JANUS CLSOCK</var> rule in place to allow access to the
local port (the first argument of <var>$Sock_Conn</var> and <var>New</var>).
Such errors are indicated by a negative value returned by <var>$Sock_Conn</var>
or by a null object returned by the <var>New</var> method.
The <var>New</var> method also returns error information to <var>$STATUSD</var> that can be queried.
For both <var>$Sock_Conn</var> and <var>New</var>, an error message is also returned to the terminal
(which you may suppress, as mentioned in
the <var>$Sock_Conn</var> and <var>New</var> method individual descriptions).

Once a socket is successfully connected, either via <var>$Sock_Conn</var> or the <var>New</var> method
(for a <var>CLSOCK</var> port),
or is socket number 1 or an object assigned by the <var>ServerSocket</var> method
(if your program is running as part of the <var>CMD</var> processing of a
<var>SRVSOCK</var> port), you have several choices for how to handle a socket
in the <var>RESET</var> state.
Specifying an <var>ONRESET</var> action in a
<var>$Sock_Set</var> or <var>Set</var> method call, you determine
what (most) <var class="product">Janus Sockets</var> $functions or methods will do if they encounter
a <var>RESET</var> socket:
<ul>
<li>Jump to a reset handling label.
<li>Cancel the request.
<li><var>CONTINUE</var> the request with the next statement after the $function or method
invocation, and return an error indicator.
</ul>
In some cases, a <var class="product">Janus Sockets</var> $function or method
can perform its operation completely, regardless of the state of the socket.
You can further refine the <var>RESET</var> handling action for a socket to specify:
<ul>
<li>In cases where the request can be performed completely, the request should
continue to the next statement.
<li>In cases where the request cannot be performed completely, the jump label
or cancel action should be performed.
</ul>

Thus, the full set of <var>ONRESET</var> actions is:
<table class="syntaxTable">
<tr><th><var>CANCEL</var>
</th><td>Cancel the request if a <var>RESET</var> socket is encountered.
</td></tr>
<tr><th><var>CANCELC</var>
</th><td>Cancel the request if a <var>RESET</var> socket is encountered, unless the operation is one that can be completely performed — in which case, continue to the next statement.
</td></tr>
<tr><th><var>CONTINUE</var>
</th><td>Continue to the next statement if a <var>RESET</var> socket is encountered.
</td></tr>
<tr><th><var>LABEL</var>
</th><td>Jump to the active <var>ONRESET</var> label if a <var>RESET</var> socket is encountered. If no <var>ONRESET</var> label is active, cancel the request.
</td></tr>
<tr><th><var>LABELC</var>
</th><td>If the operation is one that can be completely performed, continue to the next statement if a <var>RESET</var> socket is encountered. Otherwise, jump to the active <var>ONRESET</var> label if a <var>RESET</var> socket is encountered; if no <var>ONRESET</var> label is active,
cancel the request.
</td></tr></table>

Usage notes:
<ul>
<li>The jump label option requires that you make a jump label active
for the request using <var>[[$Sock_OnReset]]</var>
or using the <var>[[OnReset (Socket function)|OnReset]]</var> method.
Until and unless a label is active, the label action default is to cancel the request.
<li>Using an <var>ONRESET</var> label (or request cancellation with an <var>APSY</var> error procedure)
is a good way to centralize all of an application's sockets error handling.
Details about the error can be retrieved in
the <var>APSY</var> error procedure or at the <var>ONRESET</var> label (using <var>[[$Sock_ErrInfo]]</var>
or the <var>[[ErrInfo (Socket function)|ErrInfo]]</var> method).
<li>As with any request cancellation, if a request is running in <var>APSY</var>, the
error procedure is included.
<li>A socket <var>RESET</var> condition may be encountered by a <var class="product">User Language</var>
print operation (when print is captured) rather than by a <var class="product">Janus Sockets</var>
$function or method invocation.
In this case, the same error handling mechanisms apply, although, of course,
the print operation does not "return" any <var class="product">Janus Sockets</var> error indicator.
<li>A socket <var>RESET</var> condition may be encountered outside a <var class="product">User Language</var>
request, when print is captured and a <var class="product">Model 204</var> command produces print output.
In this case, if cancel (or a jump label) is
in effect for a capturing socket, a counting error message is issued.
</ul>

===Operations unaffected by RESET sockets===
Some <var class="product">Janus Sockets</var> $functions and methods are not affected by <var>RESET</var> situations
or do not follow the <var>ONRESET</var> setting that is in effect:
<ul>
<li>Some <var class="product">Janus Sockets</var> functions, such as <var>[[$Sock_Num]]</var>, do not have a socket number
argument, hence will not encounter a <var>RESET</var> socket, and hence are not affected
by any <var>ONRESET</var> setting nor will they return error indicators nor set the last error information.
<li>The <var>Socket</var> methods equivalent to the $functions that do not have a socket
number argument are shared methods that will not encounter a <var>RESET</var> socket, are not affected
by any <var>ONRESET</var> setting, will not return error indicators, and will not set the last error information.
<li>$Sock_xxx functions that may be invoked with -1 (meaning "all sockets"),
for example, <code>$sock_capture(-1...)<code>, do not encounter a <var>RESET</var> socket.
They will always continue to the next statement with no indication of error.
<li>If the following <var class="product">Janus Sockets</var> $unctions or methods encounter a <var>RESET</var> socket,
they will always continue to the next statement, and they will not set the last socket error information:
<ul>
<li><var>$Sock_Close</var> or the <var>Close</var> method
<li><var>$Sock_Info</var> with an <var>ONRESET</var> argument,
or the <var>Info</var> method with an <var>ONRESET</var> argument
<li><code>$Sock_Set(socknum, 'ONRESET', action)</code>,
or the <var>Set</var> method with an <var>ONRESET</var> argument
</ul>
</ul>

===Error information for a RESET socket condition===
Excepting these cases, when a <var>RESET</var> socket is encountered:
<ul>
<li>The "last socket error" information is always set.
The socket number, $function name, and error code number of the latest
<var class="product">Janus Sockets</var> $function that could not completely succeed can be obtained
by <var>$Sock_ErrInfo</var> or by the <var>ErrInfo</var> method.
<li>If the request continues at the next statement
after the $function (neither <var>ONRESET CANCEL</var> nor <var>ONRESET LABEL</var> is in effect),
an error indication is returned.
The exceptions to this are <var>[[$Sock_Tran_In]]</var> and <var>[[$Sock_Tran_Out]]</var> and their method
counterparts <var>[[TranIn (Socket function)|TranIn]]</var> and <var>[[TranOut (Socket function)|TranOut]]</var>.
These exceptions return the translated string; they do not return an error indication.
</ul>

The documentation for each <var class="product">Janus Sockets</var> $function and method
states the error indicator it returns if continuation is in effect.
If continuation is in effect, and if the operation can be completely performed
for a <var>RESET</var> socket, the documentation states that continuation is in effect
if either <var>CANCELC</var> or <var>LABELC</var> is in effect.

==Socket parameters and settings==
A number of values control the operation of a socket.
Typically, the <var>$Sock_Set</var> function
or the <var>[[Set (Socket function)|Set]]</var> method is used to change these values.
The <var>[[$Sock_Capture]]</var> function or the <var>[[Capture (Socket function)|Capture]]</var> method
is used to change the print capture setting.

The print capture setting, and all of the values that can be changed with <var>$Sock_Set</var> or <var>Set</var>, can be examined with the <var>$Sock_Info</var> function or the <var>Info</var> method
(which also allow viewing some special values that cannot be changed).
Information about the certificate provided by a remote partner (if you are
using <var class="product">Janus Network Security</var>) can be examined with <var>[[$Sock_Cert_Levels]]</var>
and <var>[[$Sock_Cert_Info]]</var>, or by
their method counterparts <var>[[CertLevels (Socket function)|CertLevels]]</var>)
and <var>[[CertInfo (Socket function)|CertInfo]]</var>.

Some socket settings, for example <var>LINEND</var>, are the same as parameters on
the <var>[[JANUS DEFINE command|JANUS DEFINE]]</var> command for the port that is used when the socket connection is made.
These values are referred to as '''socket parameters''', or, when it is
clear that the context of the discussion is about parameters on a <var>JANUS DEFINE</var>
command, simply as parameters.
The initial setting of a socket parameter is the value specified
for the parameter on the socket's associated <var>JANUS DEFINE</var> command.
If no explicit value is specified,
the socket's initial setting is the default value of that <var>JANUS DEFINE</var> parameter.

Additionally, some values that control a socket's operation can only
be set (with <var>$Sock_Set</var> or with the <var>Set</var> method) after a connection is made.
<var>RECVLIM</var> is an example.
In this documentation, these values are referred to as '''socket settings'''.
The principal purpose of this distinction is to remind you (if you need to
set one of these values for an application) whether you may simply use the port definition to set the value.

[[Category:Janus Sockets]]

← Older revision		Revision as of 18:56, 25 April 2013
Line 364:		Line 364:
	<ul>		<ul>
	<li>[[Sample Janus Sockets programs]]		<li>[[Sample Janus Sockets programs]]
	<li>Janus Sockets interfaces:		<li>Socket-level interfaces:
			<ul>
			<li>[[Janus Sockets $functions\|$functions]]
			<li>[[Socket class]]
			</ul>
			<li>Higher-level interfaces:
	<ul>		<ul>
	<li>[[Email class]]		<li>[[Email class]]

← Older revision		Revision as of 18:42, 25 April 2013
Line 363:		Line 363:
	==See also==		==See also==
	<ul>		<ul>
	<li>Sample Janus Sockets programs		<li>[[Sample Janus Sockets programs]]
			<li>Janus Sockets interfaces:
			<ul>
			<li>[[Email class]]
			<li>[[HTTP Helper\|HTTP Helper classes]]
			<li>[[LDAP class]]
			<li>[[Janus FTP Server]]
			<li>[[Janus Telnet Server]]
	</ul>		</ul>

	[[Category:Janus Sockets]]		[[Category:Janus Sockets]]

← Older revision		Revision as of 23:52, 13 February 2012
Line 1:		Line 1:
			==Introduction==
	Other Janus products are implemented with algorithms built in to the		Other Janus products are implemented with algorithms built in to the
	<var class="product">Sirius Mods</var> to		<var class="product">Sirius Mods</var> to
Line 7:		Line 8:

	<var class="product">Janus Sockets</var> is different.		<var class="product">Janus Sockets</var> is different.
	A socket is generic by design and will allow		A socket is generic by design and will allow any sort of data to be passed back and forth.
	any sort of data to be passed back and forth.
	<var class="product">Janus Sockets</var> simply provides the TCP/IP packet handling, buffering and		<var class="product">Janus Sockets</var> simply provides the TCP/IP packet handling, buffering and
	some translation services, and the User Language application is written		some translation services, and the User Language application is written to handle whatever comes wrapped in the packet.
	to handle whatever comes wrapped in the packet.
	You could, for example, write a web server using		You could, for example, write a web server using
	<var class="product">Janus Sockets</var>, but the <var class="product">User Language</var> programs would have to		<var class="product">Janus Sockets</var>, but the <var class="product">User Language</var> programs would have to
Line 22:		Line 21:
	<var class="product">Janus Sockets</var> applications that originate ''inside'' the <var class="product">Model 204</var>		<var class="product">Janus Sockets</var> applications that originate ''inside'' the <var class="product">Model 204</var>
	online require a <var class="product">Janus Sockets</var> client port		online require a <var class="product">Janus Sockets</var> client port
	(<var>[[JANUS DEFINE ~~command~~#type\|CLSOCK]]</var>) to be defined.		(<var>[[JANUS DEFINE#type\|CLSOCK]]</var>) to be defined.
	Janus applications that will respond to incoming requests		Janus applications that will respond to incoming requests
	require a <var class="product">Janus Sockets</var> server port (<var>[[JANUS DEFINE ~~command~~#type\|SRVSOCK]]) to be defined.		require a <var class="product">Janus Sockets</var> server port (<var>[[JANUS DEFINE#type\|SRVSOCK]]</var>) to be defined.

	This example shows both types of ports; it also shows <var>[[JANUS DOMAIN]]</var> and		This example shows both types of ports; it also shows <var>[[JANUS DOMAIN]]</var> and
Line 55:		Line 54:
	The only differences are:		The only differences are:
	<ul>		<ul>
	<li>A client socket must be connected by a "connect" $function		<li>A client socket must be connected by a "connect" $function (<var>[[$Sock_Conn]]</var>)
	(<var>[[$Sock_Conn]]</var>)		or <var>[[Socket class\|Socket]]</var> object <var>[[New (Socket constructor)\|New]]</var> method.
	or <var>Socket</var> object <var>[[New (Socket constructor\|New]]</var> method.
	A server socket is already connected when the server <var>[[CMD (JANUS DEFINE parameter)\|CMD]]</var> begins processing.		A server socket is already connected when the server <var>[[CMD (JANUS DEFINE parameter)\|CMD]]</var> begins processing.
	<li>Client and server socket objects are identified by number if using		<li>Client and server socket objects are identified by number if using
Line 69:		Line 67:
	socket to stay in use across <var class="product">User Language</var> requests.		socket to stay in use across <var class="product">User Language</var> requests.
	The default for a client socket is <var>CLOSE</var>.		The default for a client socket is <var>CLOSE</var>.
	This setting can be changed by specifying <var>CLOSE</var> or <var>NOCLOSE</var> on the <var>$Sock_Set</var> function		This setting can be changed by specifying <var>CLOSE</var> or <var>NOCLOSE</var> on the <var>[[$Sock_Set]]</var> function
	(but <i>not</i> on the <var>Socket</var> method <var>[[Set (Socket function)\|Set]]</var>).		(but <i>not</i> on the <var>Socket</var> method <var>[[Set (Socket function)\|Set]]</var>).
	<li>Some $function (<var>[[$Sock_Info]]</var> and <var>$Sock_Set</var>) and <var>Socket</var> method (<var>[[Info (Socket function)\|Info]]</var> and <var>Set</var>) parameters are valid only for <var>SRVSOCK</var> ports, and some are valid only for		<li>Some $function (<var>[[$Sock_Info]]</var> and <var>$Sock_Set</var>) and <var>Socket</var> method (<var>[[Info (Socket function)\|Info]]</var> and <var>Set</var>) parameters are valid only for <var>SRVSOCK</var> ports, and some are valid only for
Line 126:		Line 124:
	host name and port number) is no longer available, and the only completely		host name and port number) is no longer available, and the only completely
	meaningful operation for the socket is <var>$Sock_Close</var> or the <var>Close</var> method.		meaningful operation for the socket is <var>$Sock_Close</var> or the <var>Close</var> method.
	However, as described in [[#Handling connection errors and RESET sockets\|Handling connection errors and RESET sockets]], some operations and some		However, as described in [[#Handling connection errors and RESET sockets\|"Handling connection errors and RESET sockets"]], some operations and some situations allow you to use a <var>RESET</var> socket's socket number with certain
	situations allow you to use a <var>RESET</var> socket's socket number with certain		<var class="product">Janus Sockets</var> $functions, or to use a <var>RESET</var> socket object with certain methods.
	$~~Sock_xxx~~ functions, or to use a <var>RESET</var> socket object with certain methods.

	As stated above, saying that a socket is <var>OPEN</var> actually refers to a set of socket states.		As stated above, saying that a socket is <var>OPEN</var> actually refers to a set of socket states.
	Among these states, the use of the <var>FIN</var> indicator is significant.		Among these states, the use of the <var>FIN</var> indicator is significant.
	You use the <var>FIN</var> option of the <var>[[$Sock_Send]]</var> and <var>[[$Sock_SendLn]]</var> functions, or of the <var>[[Send (Socket function)\|Send]]</var> and <var>[[SendWithLineEnd (Socket function)\|SendWithLineEnd]]</var>) methods,		You use the <var>FIN</var> option of the <var>[[$Sock_Send]]</var> and <var>[[$Sock_SendLn]]</var> functions, or of the <var>[[Send (Socket function)\|Send]]</var> and <var>[[SendWithLineEnd (Socket function)\|SendWithLineEnd]]</var> methods,
	to specify that your application will no longer send any data on the socket.		to specify that your application will no longer send any data on the socket.

	Similarly, the remote partner on a socket may have sent the <var>FIN</var> indicator.		Similarly, the remote partner on a socket may have sent the <var>FIN</var> indicator.
	After your application has received all data on that socket, and then requested		After your application has received all data on that socket, and then requested
	additional data, <var>[[$Sock_Recv]]</var> or <var>[[$~~Sock_RecvPprs~~]]</var>,		additional data, <var>[[$Sock_Recv]]</var> or <var>[[$Sock_RecvPrs]]</var>,
	or the <var>[[Receive (Socket function)\|Receive]]</var> and		or the <var>[[Receive (Socket function)\|Receive]]</var> and
	<var>[[ReceiveAndParse (Socket function)\|ReceiveAndParse]]</var>) methods,		<var>[[ReceiveAndParse (Socket function)\|ReceiveAndParse]]</var> methods,
	will indicate that the <var>FIN</var> indication was received.		will indicate that the <var>FIN</var> indication was received.
	In these case, the socket is still <var>OPEN</var>, but it is in one of three states:		In these case, the socket is still <var>OPEN</var>, but it is in one of three states:
Line 153:		Line 150:
	Some examples of this are:		Some examples of this are:
	<ul>		<ul>
	<li>Most of the <var>~~$Sock_xxx~~</var> functions require an in-use socket		<li>Most of the <var class="product">Janus Sockets</var> $functions require an in-use socket
	number (a value returned by <var>$Sock_Conn</var>, or the special socket number 1 for		number (a value returned by <var>$Sock_Conn</var>, or the special socket number 1 for
	the inbound connection on a <var>SRVSOCK</var> port) as the first argument.		the inbound connection on a <var>SRVSOCK</var> port) as the first argument.
Line 185:		Line 182:

	A number of situations may prevent <var>$Sock_Conn</var> or <var>New</var> from succeeding:		A number of situations may prevent <var>$Sock_Conn</var> or <var>New</var> from succeeding:
	for example, there may not be a <var>JANUS CLSOCK</var> rule in place to allow access to the		for example, there may not be a <var>[[JANUS CLSOCK]]</var> rule in place to allow access to the
	local port (the first argument of <var>$Sock_Conn</var> and <var>New</var>).		local port (the first argument of <var>$Sock_Conn</var> and <var>New</var>).
	Such errors are indicated by a negative value returned by <var>$Sock_Conn</var>		Such errors are indicated by a negative value returned by <var>$Sock_Conn</var>
Line 273:		Line 270:
	number argument are shared methods that will not encounter a <var>RESET</var> socket, are not affected		number argument are shared methods that will not encounter a <var>RESET</var> socket, are not affected
	by any <var>ONRESET</var> setting, will not return error indicators, and will not set the last error information.		by any <var>ONRESET</var> setting, will not return error indicators, and will not set the last error information.
	<li>$~~Sock_xxx~~ functions that may be invoked with -1 (meaning "all sockets"),		<li><var class="product">Janus Sockets</var> $functions that may be invoked with -1 (meaning "all sockets"),
	for example, <code>$sock_capture(-1...)<code>, do not encounter a <var>RESET</var> socket.		for example, <code>$sock_capture(-1...)</code>, do not encounter a <var>RESET</var> socket.
	They will always continue to the next statement with no indication of error.		They will always continue to the next statement with no indication of error.
	<li>If the following <var class="product">Janus Sockets</var> $unctions or methods encounter a <var>RESET</var> socket,		<li>If the following <var class="product">Janus Sockets</var> $unctions or methods encounter a <var>RESET</var> socket,
Line 310:		Line 307:
	==Socket parameters and settings==		==Socket parameters and settings==
	A number of values control the operation of a socket.		A number of values control the operation of a socket.
	Typically, the <var>$Sock_Set</var> function		Typically, the <var>[[$Sock_Set]]</var> function or the <var>[[Set (Socket function)\|Set]]</var> method is used to change these values.
	or the <var>[[Set (Socket function)\|Set]]</var> method is used to change these values.
	The <var>[[$Sock_Capture]]</var> function or the <var>[[Capture (Socket function)\|Capture]]</var> method		The <var>[[$Sock_Capture]]</var> function or the <var>[[Capture (Socket function)\|Capture]]</var> method
	is used to change the print capture setting.		is used to change the print capture setting.
Line 320:		Line 316:
	using <var class="product">Janus Network Security</var>) can be examined with <var>[[$Sock_Cert_Levels]]</var>		using <var class="product">Janus Network Security</var>) can be examined with <var>[[$Sock_Cert_Levels]]</var>
	and <var>[[$Sock_Cert_Info]]</var>, or by		and <var>[[$Sock_Cert_Info]]</var>, or by
	their method counterparts <var>[[CertLevels (Socket function)\|CertLevels]]</var>)		their method counterparts <var>[[CertLevels (Socket function)\|CertLevels]]</var> and <var>[[CertInfo (Socket function)\|CertInfo]]</var>.
	and <var>[[CertInfo (Socket function)\|CertInfo]]</var>.

	Some socket settings, for example <var>LINEND</var>, are the same as parameters on		Some socket settings, for example <var>LINEND</var>, are the same as parameters on
	the <var>[[~~JANUS DEFINE command\|~~JANUS DEFINE]]</var> command for the port that is used when the socket connection is made.		the <var>[[JANUS DEFINE]]</var> command for the port that is used when the socket connection is made.
	These values are referred to as '''socket parameters''', or, when it is		These values are referred to as '''socket parameters''', or, when it is
	clear that the context of the discussion is about parameters on a <var>JANUS DEFINE</var>		clear that the context of the discussion is about parameters on a <var>JANUS DEFINE</var>

Janus Sockets User Language coding considerations - Revision history

JAL: /* See also */

JAL: /* See also */

JAL: /* Janus Sockets and Longstrings */

JAL at 18:30, 25 April 2013

JAL: /* Introduction */

JAL: /* Introduction */

JAL2 at 20:28, 14 February 2012

JAL2 at 23:52, 13 February 2012

JAL2: Created page with "Other Janus products are implemented with algorithms built in to the Sirius Mods to handle the underlying complexity of the incoming and outgoing data...."

JAL2: Created page with "Other Janus products are implemented with algorithms built in to the `Sirius Mods` to handle the underlying complexity of the incoming and outgoing data...."