MS RFC 53: Guidelines for MapScript method return values¶
- Date:
2009/03/08
- Authors:
Daniel Morissette
- Contact:
dmorissette at mapgears.com
- Last Edited:
2009/03/08
- Status:
Adopted on 2009/03/12
- Version:
MapServer 5.4
Overview¶
Ticket #244 pointed out that the return values of MapScript methods were not consistent: some methods return 0/-1 for success/failure and others return MS_SUCCESS/MS_FAILURE.
This mini-RFC defines guidelines for the return values to use with MapScript methods in the future.
Technical Solution¶
Existing methods will remain untouched to avoid breaking existing MapScript applications.
For new methods added to the MapScript API in the future, the following guidelines should apply:
Return values:
If the method returns only a success/failure status then the MS_SUCCESS/MS_FAILURE values should be used.
If the method returns a reference to an object, then it should return a valid object on success, or a NULL value on failure
If the method returns an positive integer, then it should return a positive integer on success and -1 on failure. This is a flexible rule which may not apply in some contexts.
Error reporting:
In case of errors/failures, MapScript developers should ensure that the MapScript application code can expect to find an errorObj in the error stack. In most cases the core function that MapScript maps to should take care of calling msSetError(), but in some cases the error may be caught by the wrapper code and then the wrapper code may be responsible for calling msSetError() on failure to ensure that the caller has valid error information.
Backwards Compatibility Issues¶
None. These guidelines apply only to new MapScript methods. The existing MapScript API remains untouched.
Ticket Id¶
Voting History¶
Adopted on 2009/03/12 with +1 from DanielM, UmbertoN, TomK, SteveW, TamasS, HowardB, AssefaY, PericlesN, JeffM and SteveL.