View source for $Sock OnReset

{{DISPLAYTITLE:$Sock_OnReset}}
<span class="pageSubtitle">Set label to handle RESET conditions</span>
<p class="warn"><b>Note: </b>Many $functions have been deprecated in favor of Object Oriented
methods. The OO equivalent for <var>$Sock_OnReset</var> is the <var>[[OnReset (Socket function)|OnReset]]</var> method.</p>

<var>$Sock_OnReset</var> specifies a label in the <var class="product">User Language</var> sockets program to
jump to when a <var>RESET</var> socket is encountered in the current or lower scope.

<var>$Sock_OnReset</var> is also [[Notation conventions for methods#Callable functions|callable]].

==Syntax==
<p class="syntax"><span class="squareb">[</span><span class="term">%rc</span><span class="literal"> =</span><span class="squareb">]</span><span class="literal"> = $Sock_OnReset(</span><span class="term">label</span><span class="literal">)</span>  </p>
[[Category: Janus Sockets $functions]]

===Syntax terms===
<table class="syntaxTable">
<tr><th>%rc</th>
<td>A numeric value that indicates whether the program jump is successful. 0 means success.</td></tr> 
<tr><th>label</th> 
<td>A string that identifies the label that is to handle <var>RESET</var> conditions. </td></tr> 
</table>

==Usage notes== 
<ul> 
<li><var>$Sock_OnReset</var> does not have a socket number argument, thus it is not affected by any <var>ONRESET</var> setting.
<li>If <var class="term">label</var> is the null string or all blanks, any existing <var>ONRESET</var> label in the current scope is cleared, and <var>$Sock_OnReset</var> returns: 
<ul> 
<li>-3, if $SOCK_ONRESET is issued from an ON unit 
<li>-1, otherwise 
</ul>
Otherwise, if the argument is a valid label and the function call is successful, it replaces any existing <var>ONRESET</var> label definition in the current scope and returns a 0.

<li>If the function call fails to clear or set the <var>ONRESET</var> label, the request is cancelled. The function can fail for the following reasons: 
<ul> 
<li>The label is not found in the current scope. 
<li>The label is a subroutine. 
<li><var>$Sock_OnReset</var> is invoked from an <var>ON</var> unit, and the argument is neither the null string nor all blank. <li>Label is in a loop, <var>ON</var> unit, or simple subroutine. 
</ul> 

<li>A request may have multiple <var>ONRESET</var> labels set, up to one for each scope (the outer level of a request is a scope, as is each complex subroutine). A jump to an <var>ONRESET</var> label is attempted when a <var>RESET</var> socket is encountered during a <var class="product">Janus Sockets</var> operation and the socket's <var>ONRESET</var> setting is <code>LABEL</code>. If the operation requires an <var>OPEN</var> socket, a socket can have the <var>LABELC</var> setting. See [[Janus Sockets User Language coding considerations#Handling connection errors and RESET sockets|"Handling connection errors and RESET sockets"]] for an explanation of the <var>ONRESET</var> setting.
<p>
When the jump is attempted, it is successful if there is an <var>ONRESET</var> label within the current or an invoking scope of the <var class="product">User Language</var> request that encountered the <var>RESET</var> socket. If there is no such label, the <var class="product">User Language</var> request is cancelled. </p>

<li>Using this function to set an <var>ONRESET</var> handler reduces the amount of return code checking the application has to do on each $Sock_xxx function call. 
</ul> 

==Example== 
As a result of the <var>$Sock_OnReset</var> code in the following example, encountering a <var>RESET</var> socket will print a set of error messages that provide the failing operation, return code, and socket identifier before terminating evaluation: 
<p class="code">%x = $Sock_OnReset('KABOOM')
  ...

KABOOM: 
%c =  $Sock_ErrInfo('CODE') 
%s =  $Sock_ErrInfo('SOCKNUM') 
%f =  $Sock_ErrInfo('FUN') 
Print 'The connection was unexpectedly lost.' 
Print 'The last sockets error operation was:' 
Print 'Function:      ' With %f 
Print 'Return code:   ' With %c 
Print 'Socket:        ' With %s 
STOP 
</p>

[[Category: Janus Sockets $functions]]