OnReset (Socket function)
<section begin=dpl_desc/><section end=dpl_desc/>
OnReset is a member of the Socket class.
This callable, shared method specifies the label in the User Language sockets program to jump to when a RESET socket is encountered in the current or a lower program scope. It can also be used to clear without replacing an existing ONRESET label. The OnReset function has an effect similar to $Sock_Onreset.
Syntax
%rc = %(Socket):OnReset[('label')]
Syntax terms
| %rc | Numeric return string, which is to contain 0 (success) or a negative integer (see label, below). |
|---|---|
| %(Socket) | The class name in parentheses denotes a shared method. Specifying %(Socket): is not the only way to invoke the method (see ?? refid=themeth.).
|
| label | The label in the program to which to jump to for ONRESET handling. If label is the null string or all blanks, any existing ONRESET label in the current scope is cleared, and OnReset returns:
|
Usage notes
- If label is a valid label and the OnReset function call is successful, any existing ONRESET label definition in the current scope is replaced, and OnReset returns 0.
- If the OnReset call fails to clear or to set the ONRESET label, the request is cancelled.
OnReset can fail for the following reasons:
- label is not found in the current scope.
- label is a subroutine.
- OnReset is invoked from an ON unit, and label is neither the null string nor all blank.
- label is in a loop, ON unit, or simple subroutine.
- OnReset is not affected by any ONRESET setting.
- A request may have multiple ONRESET labels set: as many as one for each
scope (the outer level of a request is a scope, as is each complex subroutine).
As described in "Handling connection errors and RESET sockets",
a jump to an ONRESET label is attempted if both of these are true:
- A RESET socket is encountered during a Janus Sockets operation
- The socket's ONRESET setting
is
LABEL(orLABELC, if the operation requires an OPEN socket)
- An attempted jump to a label is successful if there is an ONRESET label within the current or an invoking scope of the User Language request that encountered the RESET socket. If there is no such label, the User Language request is cancelled.
- Using OnReset to set an ONRESET handler reduces the amount of return code checking the application has to do on each method call.
Example
As a result of the OnReset code in the following example, encountering a RESET socket will print a set of error messages that provide the failing operation, return code, and socket identifier before terminating evaluation:
Call %(Socket):OnReset('KABOOM') ... KABOOM: %c = %(Socket):Errinfo('CODE') %s = %(Socket):Errinfo('SOCKNUM') %f = %(Socket):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