$Sock_OnReset

Set label to handle RESET conditions

Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for $Sock_OnReset is the OnReset method.

$Sock_OnReset specifies a label in the User Language sockets program to jump to when a RESET socket is encountered in the current or lower scope.

$Sock_OnReset is also callable.

Syntax

[%rc =] = $Sock_OnReset(label)

Syntax terms

%rc	A numeric value that indicates whether the program jump is successful. 0 means success.
label	A string that identifies the label that is to handle RESET conditions.

Usage notes

• $Sock_OnReset does not have a socket number argument, thus it is not affected by any ONRESET setting.
• If label is the null string or all blanks, any existing ONRESET label in the current scope is cleared, and $Sock_OnReset returns:
  • -3, if $SOCK_ONRESET is issued from an ON unit
  • -1, otherwise

  Otherwise, if the argument is a valid label and the function call is successful, it replaces any existing ONRESET label definition in the current scope and returns a 0.

• If the function call fails to clear or set the ONRESET label, the request is cancelled. The function can fail for the following reasons:
  • The label is not found in the current scope.
  • The label is a subroutine.
  • $Sock_OnReset is invoked from an ON unit, and the argument is neither the null string nor all blank.
  • Label is in a loop, ON unit, or simple subroutine.
• A request may have multiple ONRESET 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 ONRESET label is attempted when a RESET socket is encountered during a Janus Sockets operation and the socket's ONRESET setting is LABEL. If the operation requires an OPEN socket, a socket can have the LABELC setting. See "Handling connection errors and RESET sockets" for an explanation of the ONRESET setting.

  When the jump is attempted, it 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 this function to set an ONRESET handler reduces the amount of return code checking the application has to do on each $Sock_xxx function call.

Example

As a result of the $Sock_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:

%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