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
