Sets various error handling options.
Synopsis with Optional Arguments
#include <imsls.h>
void
imsls_error_options (
IMSLS_SET_PRINT,
Imsls_error type, int
setting,
IMSLS_SET_STOP,
Imsls_error type, int
setting,
IMSLS_SET_TRACEBACK,
Imsls_error type, int
setting,
IMSLS_FULL_TRACEBACK, int
setting,
IMSLS_GET_PRINT,
Imsls_error type, int
*psetting,
IMSLS_GET_STOP,
Imsls_error type, int
*psetting,
IMSLS_GET_TRACEBACK,
Imsls_error type, int
*psetting,
IMSLS_SET_ERROR_FILE, FILE
*file,
IMSLS_GET_ERROR_FILE, FILE
**pfile,
IMSLS_ERROR_MSG_PATH, char
*path,
IMSLS_ERROR_MSG_NAME, char
*name,
IMSLS_ERROR_PRINT_PROC,
Imsls_error_print_proc print_proc,
IMSLS_SET_SIGNAL_TRAPPING, int
setting,
0)
Optional Arguments
IMSLS_SET_PRINT, Imsls_error
type,
int
setting (Input)
Printing of type type error messages is
turned off if setting is 0;
otherwise, printing is turned on.
Default: Printing turned on for IMSLS_WARNING, IMSLS_FATAL, IMSLS_TERMINAL, IMSLS_FATAL_IMMEDIATE,
and
IMSLS_WARNING_IMMEDIATE messages
IMSLS_SET_STOP,
Imsls_error type, int setting
(Input)
Stopping on type type error messages is
turned off if setting is 0;
otherwise, stopping is turned on.
Default: Stopping turned on for IMSLS_FATAL and IMSLS_TERMINAL
and
IMSLS_FATAL_IMMEDIATE messages
IMSLS_SET_TRACEBACK,
Imsls_error type, int setting
(Input)
Printing of a traceback on type type error messages is
turned off if setting is 0;
otherwise, printing of the traceback turned on.
Default: Traceback
turned off for all message types
IMSLS_FULL_TRACEBACK, int setting
(Input)
Only documented functions are listed in the traceback if setting is 0;
otherwise, internal function names also are listed.
Default: Full traceback
turned off
IMSLS_GET_PRINT,
Imsls_error type, int *psetting
(Output)
Sets the integer pointed to by psetting to the
current setting for printing of type type error messages.
IMSLS_GET_STOP,
Imsls_error type, int *psetting
(Output)
Sets the integer pointed to by psetting to the
current setting for stopping on type type error messages.
IMSLS_GET_TRACEBACK, Imsls_error
type,
int
*psetting (Output)
Sets the integer pointed to
by psetting to the
current setting for printing of a traceback for type type error
messages.
IMSLS_SET_ERROR_FILE, FILE *file
(Input)
Sets the error output file.
Default: file = stderr
IMSLS_GET_ERROR_FILE,
FILE
**pfile (Output)
Sets the FILE * pointed to by
pfile to the
error output file.
IMSLS_ERROR_MSG_PATH, char *path
(Input)
Sets the error message file path. On UNIX systems, this is a
colon-separated list of directories to be searched for the file containing the
error messages.
Default: system dependent
IMSLS_ERROR_MSG_NAME, char *name
(Input)
Sets the name of the file containing the error messages.
Default:
file = "imsls_e.bin"
IMSLS_ERROR_PRINT_PROC,
Imsls_error_print_proc
print_proc (Input)
Sets the error printing function. The
procedure print_proc has the
form void print_proc
(Imsls_error type, long code, char *function_name, char *message).
In this case, type is the error message type number (IMSLS_FATAL, etc.), code is the error message code number (IMSLS_MAJOR_VIOLATION, etc.), function_name is the name of the function setting the error, and message is the error message to be printed. If print_proc is NULL, then the default error printing function is used.
IMSLS_SET_SIGNAL_TRAPPING, int setting
(Input)
C/Stat/Library will use its own signal handler if setting is 1;
otherwise the C/Stat/Library signal handler is not used. If C/Stat/Library
is called from a multi-threaded application, signal handling by C/Stat/Library
must be turned off. See Example 3 for
details.
Default: setting = 1
Return Value
The return value is void.
Description
This function allows the error handling system to be customized.
If multiple threads are used then default settings are valid for each thread but can be altered for each individual thread. When using threads it is necessary to set options (excluding IMSLS_SET_SIGNAL_TRAPPING ) for each thread by calling imsls_error_options from within each thread.
The IMSL signal-trapping mechanism must be disabled when multiple threads are used. The IMSL signal-trapping mechanism can be disabled by making the following call before any threads are created:
imsls_error_options(IMSLS_SET_SIGNAL_TRAPPING, 0, 0);
See Example 3 and Example 4 for multithreaded examples.
NOTE: Signal handlers are installed when a C/Stat/Library function is called, then uninstalled prior to returning from the C/Stat/Library function. The library function imsls_error_options can be used to perform many different tasks with regard to error handling and it will install signal handlers when first called, even if the call is being made to disable signal handling through the use of the optional argument IMSLS_SET_SIGNAL_TRAPPING. However, there may be cases when it is desirable to completely avoid any installation of signal handlers by C/Stat/Library functions. In these cases, the following function can be called.
#include <imsls.h>
void imsls_skip_signal_handler( );
Examples
Example 1
In this example, the IMSLS_TERMINAL print setting is retrieved. Next, stopping on IMSLS_TERMINAL errors is turned off, output to standard output is redirected, and an error is deliberately caused by calling imsls_error_options with an illegal value.
#include <imsls.h>
#include <stdio.h>
int main()
{
int setting;
/* Turn off stopping on IMSLS_TERMINAL */
/* error messages and write error */
/* messages to standard output */
imsls_error_options(IMSLS_SET_STOP, IMSLS_TERMINAL, 0,
IMSLS_SET_ERROR_FILE, stdout,
0);
/* Call imsls_error_options() with */
/* an illegal value */
imsls_error_options(-1);
/* Get setting for IMSLS_TERMINAL */
imsls_error_options(IMSLS_GET_PRINT, IMSLS_TERMINAL, &setting,
0);
printf("IMSLS_TERMINAL error print setting = %d\n", setting);
}
Output
*** TERMINAL Error from imsls_error_options. There is an error with
*** argument number 1. This may be caused by an incorrect number of
*** values following a previous optional argument name.
IMSLS_TERMINAL error print setting = 1
Example 2
In this example, IMSL’s error printing function has been substituted for the standard function. Only the first four lines are printed below.
#include <imsls.h>
#include <stdio.h>
void print_proc(Imsls_error, long, char*, char*);
int main()
{
/* Turn off tracebacks on IMSLS_TERMINAL */
/* error messages and use a custom */
/* print function */
imsls_error_options(IMSLS_ERROR_PRINT_PROC, print_proc,
0);
/* Call imsls_error_options() with an */
/* illegal value */
imsls_error_options(-1);
}
void print_proc(Imsls_error type, long code, char *function_name,
char *message)
{
printf("Error message type %d\n", type);
printf("Error code %d\n", code);
printf("From function %s\n", function_name);
printf("%s\n", message);
}
Output
Error message type 5
Error code 103
From function imsls_error_options
There is an error with argument number 1. This may be caused by an incorrect number of values following a previous optional argument name.
Example 3
In this example, two threads are created and error options
is called within each thread to set the error handling options slightly
different for each thread. Since we expect to generate terminal errors in
each thread, we must turn off stopping on terminal errors for each thread. Also
notice that imsls_error_options
is called from main
to disable the IMSL signal-trapping mechanism.
See Example 4
for a similar example, using WIN32 threads. Note since multiple threads are
executing, the order of the errors output may differ on some systems.
#include <pthread.h>
#include <stdio.h>
#include <imsls.h>
void *ex1(void* arg);
void *ex2(void* arg);
int main()
{
pthread_t thread1;
pthread_t thread2;
/* Disable IMSL signal trapping. */
imsls_error_options(IMSLS_SET_SIGNAL_TRAPPING, 0, 0);
/* Create two threads. */
if (pthread_create(&thread1, NULL ,ex1, (void *)NULL) != 0)
perror("pthread_create"), exit(1);
if (pthread_create(&thread2, NULL ,ex2, (void *)NULL) != 0)
perror("pthread_create"), exit(1);
/* Wait for threads to finish. */
if (pthread_join(thread1, NULL) != 0)
perror("pthread_join"),exit(1);
if (pthread_join(thread2, NULL) != 0)
perror("pthread_join"),exit(1);
}
void *ex1(void* arg)
{
float res;
/*
* Call imsls_error_options to set the error handling
* options for this thread.
*/
imsls_error_options(IMSLS_SET_STOP, IMSLS_TERMINAL, 0, 0);
res = imsls_f_beta(-1.0, .5);
}
void *ex2(void* arg)
{
float res;
/*
* Call imsls_error_options to set the error handling
* options for this thread. Notice that tracebacks are
* turned on for IMSLS_TERMINAL errors.
*/
imsls_error_options(IMSLS_SET_STOP, IMSLS_TERMINAL, 0,
IMSLS_SET_TRACEBACK, IMSLS_TERMINAL, 1, 0);
res = imsls_f_gamma(-1.0);
}
Output
*** TERMINAL Error from imsls_f_beta. Both "x" = -1.000000e+00 and "y" =
*** 5.000000e-01 must be greater than zero.
*** TERMINAL Error from imsls_f_gamma. The argument for the function can
*** not be a negative integer. Argument "x" = -1.000000e+00.
Here is a traceback of the calls in reverse order.
Error Type Error Code Routine
---------- ---------- -------
IMSLS_TERMINAL IMSLS_NEGATIVE_INTEGER imsls_f_gamma
Example 4
In this example the WIN32 API is used to demonstrate the same functionality as shown in Example 3 above. Note since multiple threads are executing, the order of the errors output may differ on some systems.
#include <windows.h>
#include <stdio.h>
#include <imsls.h>
DWORD WINAPI ex1(void *arg);
DWORD WINAPI ex2(void *arg);
int main(int argc, char* argv[])
{
HANDLE thread[2];
imsls_error_options(IMSLS_SET_SIGNAL_TRAPPING, 0, 0);
thread[0] = CreateThread(NULL, 0, ex1, NULL, 0, NULL);
thread[1] = CreateThread(NULL, 0, ex2, NULL, 0, NULL);
WaitForMultipleObjects(2, thread, TRUE, INFINITE);
}
DWORD WINAPI ex1(void *arg)
{
float res;
/*
* Call imsls_error_options to set the error handling
* options for this thread.
*/
imsls_error_options(IMSLS_SET_STOP, IMSLS_TERMINAL, 0,
0);
res = imsls_f_beta(-1.0, .5);
return(0);
}
DWORD WINAPI ex2(void *arg)
{
float res;
/*
* Call imsls_error_options to set the error handling
* options for this thread. Notice that tracebacks are
* turned on for IMSLS_TERMINAL errors.
*/
imsls_error_options(IMSLS_SET_STOP, IMSLS_TERMINAL, 0,
IMSLS_SET_TRACEBACK, IMSLS_TERMINAL, 1,
0);
res = imsls_f_gamma(-1.0);
return(0);
}
Output
*** TERMINAL Error from imsls_f_beta. Both "x" = -1.000000e+000 and "y" =
*** 5.000000e-001 must be greater than zero.
*** TERMINAL Error from imsls_f_gamma. The argument for the function can
*** not be a negative integer. Argument "x" = -1.000000e+000.
Here is a traceback of the calls in reverse order.
Error Type Error Code Routine
---------- ---------- -------
IMSLS_TERMINAL IMSLS_NEGATIVE_INTEGER imsls_f_gamma USER
