[Mapserver-dev] Error stack system

[Daniel Morissette]

Hi everyone,

Back in January we had a discussion about adding an error stack in 
MapServer to help reporting multiple errors, mostly with things 
like rendering a map composed of multiple WMS layers.

I have finally implemented this.  No worries, there are no changes for
those who don't care about the error stack.  Simply calling msGetErrorObj() 
as usual will continue to work.  Errors are automagically added to the
stack when msSetError() is called, so there is no change required in 
the code that logs errors either.

For those who need access to the stack of error, here is what you 
need to know.  First it's not really a stack, I implemented it as a
chained list in which the first item is the most recent, so it appears
as a stack.  As mentioned above, msGetErrorObj() still returns you the
most recent errorObj, which also happens to be the head of the chained
list, so to access the rest of the list, use ms_error->next until you
hit a next == NULL.

Finally, the caller (MapScript, or the mapserv CGI) is responsible of
clearing the list of errors using msResetErrorList() if/when they 
think it is necessary.

This should all be available in MapScript automagically via the SWIG
wrappers I believe, and I also added wrappers in PHP MapScript.  The
PHP documentation is included below.

Enjoy!

Daniel
-- 
------------------------------------------------------------
 Daniel Morissette               morissette at dmsolutions.ca
 DM Solutions Group              http://www.dmsolutions.ca/
------------------------------------------------------------


errorObj
--------

   Instances of errorObj are created internally by MapServer as errors
   happen.  Errors are managed as a chained list with the first item being
   the most recent error.  The head of the list can be fetched using 
   ms_GetErrorObj(), and the list can be cleared using ms_ResetErrorList()

 Functions:

   errorObj ms_GetErrorObj()
        Returns a reference to the head of the list of errorObj.

   void ms_ResetErrorList()
        Clear the current error list.  
        Note that clearing the list invalidates any errorObj handles obtained 
        via the $error->next() method.

 Members:

   int      code      /* See error code constants above */
   string   routine
   string   message

 Method:

   errorObj next()
        Returns the next errorObj in the list, or NULL if we reached the end
        of the list.

 Example:
   This example draws a map and reports all errors generated during
   the draw() call, errors can potentially come from multiple layers.

       ms_ResetErrorList();
       $img = $map->draw();
       $error = ms_GetErrorObj();
       while($error && $error->code > 0)
       {
           printf("Error in %s: %s<br>\n", $error->routine, $error->message);
           $error = $error->next();
       }