ImageGear Professional DLL v17.1 for Windows Accusoft
Error Detection and Handling
Send Feedback  
ImageGear Professional DLL v17.1 for Windows > User Guide > Using ImageGear > General Aspects > Error Detection and Handling

Glossary Item Box

ImageGear functions handle all errors in a single, uniform way. Even low-level ImageGear functions that you cannot call directly handle errors in this same way.

When an error condition is detected by an ImageGear function, the function places an error code indicating specifically what happened, along with information about where the error occurred, in an internal memory area called the ImageGear error stack. This error stack remains available to your application as it executes, so you can inspect and treat the errors where (in your program code) needed. After placing the error or errors on the error stack, the ImageGear function returns to its caller (returning the count of errors now on the stack, if the function's return type is AT_ERRCOUNT).

More than one error may be placed on the error stack as a result of a single ImageGear function call. This is because an ImageGear function that you call will often call lower-level ImageGear functions (not directly callable by your application). Each such lower level function may itself place an error onto the error stack before returning to its caller. Upon return to your application, there may be several errors on the stack. Note that in such a case, the lowest level function's error was placed on the stack first, and the highest level function (the one that your application called directly) placed its error on the stack last, just before returning to your application, because it could not proceed (due to the error).

ImageGear provides four basic functions for accessing the error stack. They are:

IG_error_clear() Clear the error stack.
IG_error_check() Obtain the number of errors on the error stack.
IG_error_get() Get a specified error from the error stack.
IG_error_set() Place an error on the error stack. This function can be useful for the forced termination of loading or saving procedures if you have defined your own callback routines.

The example below shows how you may use some of the above functions to display in a Message Window on your screen every error that is on the ImageGear error stack. Refer to descriptions of these functions in the Core Component API Function Reference for thorough explanations of their arguments.

  Copy Code 
HIGEAR hImage; /* Will hold handle of image loaded below */
INT i; /* Will hold Loop Index and Error Index */
INT iLineNumber; /* Will hold returned Line Number */
BYTEszFileName[30]; /* Will hold ret'd module name, <= 29 chars */
INT cbFileNameSize; /* Will hold size of szFileName array */
AT_ERRCODE  iCode; /* Will hold returned ImageGear Error Code */
AT_ERRCOUNT  nErrcount; /* Will hold count of errors on error stack  */
BYTE szBuf[60]; /* Will hold zero-terminated string returned by wsprintf() below */
cbFileNameSize = 30; /* Size of module-name array */
IG_load_file ("picture.bmp", &hImage ); /* Try to load image */
nErrcount = IG_error_check(); /* Get number of errors on stack */
for ( i = 0;  i < nErrcount;  i++ )  /* For each error on stack:                                         */
    {
    /* Get Module Name, Line Number, and Error Code:                *
    IG_error_get ( i, (LPSTR) &szFileName, cbFileNameSize, 
            &iLineNumber, (LPAT_ERRCODE) &iCode, NULL, NULL );
/* Format error message in szBuf: */
    wsprintf ( szBuf, "Error %d in Module %s at Line %d", iCode, 
              szFileName, iLineNumber );
/* Display error message in a Message Box, with heading "Error":*/
    MessageBox ( NULL, szBuf, "Error", MB_OK );
    }IG_error_clear();/* Done getting errors, clear the error stack */

This example displays the error number (iCode) in the Message Box. Text describing the nature of the error, and the ImageGear Error Name (such as IGE_OUT_OF_MEMORY) can be found in file GEARERRS.H.

It should be noted that each ImageGear function, excluding all IG_dspl_...() functions, clears the error stack upon entry. Therefore, after an ImageGear function call you should check the stack prior to your next ImageGear function call. Also, many ImageGear functions return as their value the value of IG_error_check(). So it is usually not necessary to call IG_error_check(). For example, the load-file and error-check statements in the above example could have been combined into one:

  Copy Code 
nErrcount = IG_load_file ( "picture.bmp", &hImage );
/* nErrcount now = number of errors place on stack during load attempt */
for ( i = 0;  i < nErrcount;  i++ )
     ...

The following ImageGear functions may also help with error stack processing:

©2012. Accusoft Corporation. All Rights Reserved.