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

  1. Since the default behavior of PyIMSL error handling is to stop execution on IMSLS_TERMINAL and IMSLS_FATAL errors, execution of the main program stops when the IMSLS_STOP_USER_FCN error message is issued unless you alter this behavior by turning stopping off using errorOptions.
  2. 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.
  3. 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