set_user_fcn_return_flag
Indicates a condition has occurred in a user-supplied function necessitating a return to the calling function.
Synopsis
#include <imsls.h>
void imsls_set_user_fcn_return_flag (int 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, imsls_set_user_fcn_return_flag stops executing any IMSL algorithm that has called the function, and returns to the calling function or main program. On invocation of imsls_set_user_fcn_return_flag, a flag is set in the IMSL 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 IMSL 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 imsls_error_options.
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
Example 1
This example is based on
imsls_f_kolmogorov_one. 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.
#include <imsls.h>
#include <stdio.h>
float cdf(float);
int main()
{
float *statistics = NULL, *diffs = NULL, *x = NULL;
int nobs = 100, nmiss;
imsls_random_seed_set(123457);
x = imsls_f_random_uniform(nobs, 0);
/* Turn off stopping on IMSLS_FATAL errors. */
imsls_error_options(IMSLS_SET_STOP, IMSLS_FATAL, 0, 0);
statistics = imsls_f_kolmogorov_one(cdf, nobs, x,
IMSLS_N_MISSING, &nmiss,
IMSLS_DIFFERENCES, &diffs,
0);
/* The following lines will be executed because
stopping is turned off. */
if (statistics) {
printf("D = %8.4f\n", diffs[0]);
printf("D+ = %8.4f\n", diffs[1]);
printf("D- = %8.4f\n", diffs[2]);
printf("Z = %8.4f\n", statistics[0]);
printf("Prob greater D one sided = %8.4f\n", statistics[1]);
printf("Prob greater D two sided = %8.4f\n", statistics[2]);
printf("N missing = %d\n", nmiss);
} else {
printf("\"statistics\" is NULL.\n");
}
}
float cdf(float x)
{
float mean = .5, std = .2886751, z, result;
/* For a hypothetical reason, stop execution when x > 0.5. */
if (x > 0.5) {
imsls_set_user_fcn_return_flag(1);
return 0;
}
z = (x-mean)/std;
result = imsls_f_normal_cdf(z);
return result;
}
Output
*** FATAL Error IMSLS_STOP_USER_FCN from imsls_f_kolmogorov_one. Request
*** from user supplied function to stop algorithm. User flag = "1".
"statistics" is NULL.
Example 2
This example is based on
imsls_f_chi_squared_test, Example 3. This example demonstrates how to handle the error condition if the user-supplied function calls a C Stat Library function. In this example,
THETA is set to 0 to force an error condition in calling the
imsls_f_poisson_cdf function in the user-supplied function.
#include <imsls.h>
#include <stdio.h>
#define SEED 123457
#define N_CATEGORIES 10
#define N_PARAMETERS_ESTIMATED 0
#define N_NUMBERS 1000
#define THETA 0.0
float user_proc_cdf(float);
int main()
{
int i, *poisson;
float cell_statistics[3][N_CATEGORIES];
float chi_squared_statistics[3], x[N_NUMBERS];
float cutpoints[] = {1.5, 2.5, 3.5, 4.5, 5.5, 6.5,
7.5, 8.5, 9.5};
char *cell_row_labels[] = {"count", "expected count",
"cell chi-squared"};
char *cell_col_labels[] = {"Poisson value", "0", "1", "2",
"3", "4", "5", "6", "7",
"8", "9"};
char *stat_row_labels[] = {"chi-squared",
"degrees of freedom","p-value"};
/* Turn off stopping on IMSLS_FATAL errors. */
imsls_error_options(IMSLS_SET_STOP, IMSLS_FATAL, 0, 0);
imsls_random_seed_set(SEED);
/* Generate the data */
poisson = imsls_random_poisson(N_NUMBERS, 5.0, 0);
/* Copy data to a floating point vector*/
for (i = 0; i < N_NUMBERS; i++)
x[i] = poisson[i];
chi_squared_statistics[2] =
imsls_f_chi_squared_test(user_proc_cdf, N_NUMBERS,
N_CATEGORIES, x,
IMSLS_CUTPOINTS_USER, cutpoints,
IMSLS_CELL_COUNTS_USER, &cell_statistics[0][0],
IMSLS_CELL_EXPECTED_USER, &cell_statistics[1][0],
IMSLS_CELL_CHI_SQUARED_USER, &cell_statistics[2][0],
IMSLS_CHI_SQUARED, &chi_squared_statistics[0],
IMSLS_DEGREES_OF_FREEDOM, &chi_squared_statistics[1],
0);
/* The following lines will be executed because
stopping is turned off. */
if (chi_squared_statistics[2] != chi_squared_statistics[2]) {
printf("p-value = NaN\n");
} else {
imsls_f_write_matrix("\nChi-squared Statistics\n", 3, 1,
&chi_squared_statistics[0],
IMSLS_ROW_LABELS, stat_row_labels,
0);
imsls_f_write_matrix("\nCell Statistics\n", 3, N_CATEGORIES,
&cell_statistics[0][0],
IMSLS_ROW_LABELS, cell_row_labels,
IMSLS_COL_LABELS, cell_col_labels,
IMSLS_WRITE_FORMAT, "%9.1f",
0);
}
}
float user_proc_cdf(float k)
{
float cdf_v;
int setting;
/* The user is responsible for checking error conditions in the
user-supplied function, even if the user-supplied function
is calling an IMSL function.
For theta = 0.0 (an invalid input), imsls_f_poisson_cdf issues
an IMSLS_TERMINAL error. Thus, stopping is turned off on
IMSLS_TERMINAL eorror. */
/* Get the current terminal error stopping setting which will be
used for restoring the setting later. */
imsls_error_options(IMSLS_GET_STOP, IMSLS_TERMINAL, &setting, 0);
/* Disable stopping on terminal error. */
imsls_error_options(IMSLS_SET_STOP, IMSLS_TERMINAL, 0, 0);
cdf_v = imsls_f_poisson_cdf ((int) k, THETA);
/* If there is terminal error, stop and return to main. */
if (imsls_error_type() == IMSLS_TERMINAL) {
imsls_set_user_fcn_return_flag(1);
return 0;
}
/* Restore stopping setting */
imsls_error_options(IMSLS_SET_STOP, IMSLS_TERMINAL, setting, 0);
return cdf_v;
}
Output
*** TERMINAL Error from imsls_f_poisson_cdf. The mean of the Poisson
*** distribution, "theta" = 0.000000e+000, must be positive.
*** FATAL Error IMSLS_STOP_USER_FCN from imsls_f_chi_squared_test.
*** Request from user supplied function to stop algorithm. User
*** flag = "1".
p-value = NaN
