setUserFcnReturnFlag

Indicates a condition has occurred in a user-supplied function necessitating a return to the calling function.

Synopsis

setUserFcnReturnFlag (code)

Required Arguments

int code (Input)

A user-defined number that indicates the reason for the return from the user-supplied function.

Description

Given a certain condition in a user-supplied function, setUserFcnReturnFlag stops executing any PyIMSL algorithm that has called the function and then returns to the calling function or main program. Upon invocation of setUserFcnReturnFlag, a flag is set in the PyIMSL error handler. Upon returning from the user-supplied function, the error IMSL_STOP_USER_FCN is issued with severity FATAL. Typically, if you use this function, you would disable stopping on IMSL C MATH errors, thus gaining greater control in situations where you need to prematurely return from an algorithm. (See Programming Notes.)

Programming Notes

• Since the default behavior of IMSL error handling is to stop execution on TERMINAL and FATAL errors, execution of the main program stops when the IMSL_STOP_USER_FCN error message is issued.
• In a user-supplied function, the user is responsible for checking error conditions such as memory allocation, return status for any function calls, valid return values, etc.
• Use of this function is valid only if called from within a user-supplied function.

Example

This example is based on intFcn. In this example, the user, for any hypothetical reason, wants to stop the evaluation of the user-supplied function, fcn, when x is less than 0.5.

from __future__ import print_function
from numpy import *
from pyimsl.math.intFcn import intFcn
from pyimsl.math.setUserFcnReturnFlag import setUserFcnReturnFlag

exact = 8.389


def fcn(x):
    if x < 0.5:
        setUserFcnReturnFlag(1)
        return (0)
    res = x * (exp(x))
    return res


# Evaluate the integral
q = intFcn(fcn, 0.0, 2.0)

# Print the result and the exact answer
print("integral = %10.3f\nexact = %10.3f" % (q, exact))

Output

***
*** Fatal error issued from IMSL function intFcn:
*** Request from user supplied function to stop algorithm.  User flag = "1".
***
Traceback (most recent call last):
  File "../../examples/math/ch12/setUserFcnReturnFlag_math_ex1.py", line 33, in <module>
    q = intFcn(fcn, 0.0, 2.0)
  File "/build2/jenkins/workspace/PyIMSL_master/pyimsl/math/intFcn.py", line 108, in intFcn
    fatalErrorCheck(MATH)
  File "/build2/jenkins/workspace/PyIMSL_master/pyimsl/util/imslUtils.py", line 451, in fatalErrorCheck
    _mathErrorHandler.handleError()
  File "/build2/jenkins/workspace/PyIMSL_master/pyimsl/util/ImslErrorHandler.py", line 264, in handleError
    raise ImslError(_imslErrorType, _imslErrorCode,
pyimsl.util.ImslError.ImslError: 4 (17198): R