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 returns to the calling function or main program. On
invocation of setUserFcnReturnFlag
, a flag is set in the PyIMSL error
handler. On returning from the user-supplied function, the error
IMSLS_STOP_USER_FCN
is issued with severity IMSLS_FATAL
. Typically,
if you use this function, you would disable stopping on IMSL C STAT
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 PyIMSL error handling is to stop execution
on
IMSLS_TERMINAL
andIMSLS_FATAL
errors, execution of the main program stops when theIMSLS_STOP_USER_FCN
error message is issued unless you alter this behavior by turning stopping off usingerrorOptions
. - 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.
Examples¶
This example is based on kolmogorovOne. In this example, the
user, for any hypothetical reason, wants to stop the evaluation of the
user-supplied function, cdf
when x
is greater 0.5.
from __future__ import print_function
from numpy import *
from pyimsl.stat.kolmogorovOne import kolmogorovOne
from pyimsl.stat.normalCdf import normalCdf
from pyimsl.stat.randomSeedSet import randomSeedSet
from pyimsl.stat.randomUniform import randomUniform
from pyimsl.stat.setUserFcnReturnFlag import setUserFcnReturnFlag
def cdf(x):
if x > 0.5:
setUserFcnReturnFlag(1)
return (0)
mean = .5
std = .2886751
z = (x - mean) / std
return normalCdf(z)
nobs = 100
randomSeedSet(123457)
x = randomUniform(nobs)
nMissing = []
differences = []
statistics = kolmogorovOne(cdf, x,
nMissing=nMissing, differences=differences)
if statistics is not None:
print("D = %8.4f" % (differences[0]))
print("D+ = %8.4f" % (differences[1]))
print("D- = %8.4f" % (differences[2]))
print("Z = %8.4f" % (statistics[0]))
print("Prob greater D one sided = %8.4f" % (statistics[1]))
print("Prob greater D two sided = %8.4f" % (statistics[2]))
print("N missing = %d" % (nMissing[0]))
else:
print("statistics is None.")
Output¶
***
*** Fatal error issued from IMSL function kolmogorovOne:
*** Request from user supplied function to stop algorithm. User flag = "1".
***
Traceback (most recent call last):
File "../../examples/stat/ch15/setUserFcnReturnFlag_ex1.py", line 41, in <module>
statistics = kolmogorovOne(cdf, x,
File "/build2/jenkins/workspace/PyIMSL_master/pyimsl/stat/kolmogorovOne.py", line 75, in kolmogorovOne
fatalErrorCheck(STAT)
File "/build2/jenkins/workspace/PyIMSL_master/pyimsl/util/imslUtils.py", line 456, in fatalErrorCheck
_statErrorHandler.handleError()
File "/build2/jenkins/workspace/PyIMSL_master/pyimsl/util/ImslErrorHandler.py", line 272, in handleError
raise ImslError(_imslErrorType, _imslErrorCode,
pyimsl.util.ImslError.ImslError: 4 (12116): R