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:

  1. 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.

  1. 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

https://github.com/MapServer/MapServer/issues/244

Voting History

Adopted on 2009/03/12 with +1 from DanielM, UmbertoN, TomK, SteveW, TamasS, HowardB, AssefaY, PericlesN, JeffM and SteveL.