Chapter 15: Utilities

error_options

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, stop­ping 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; oth­erwise, 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 trace­back 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 func­tion. 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

Visual Numerics, Inc.
Visual Numerics - Developers of IMSL and PV-WAVE
http://www.vni.com/
PHONE: 713.784.3131
FAX:713.781.9260