If a method raises an error (at any severity level), the method and containing methods, will return immediately back to the application code.
API methods which can generate errors have the following characteristics:
All other methods:
Either of these types of methods can assert if invalid arguments are used or an out of memory condition occurs.
Where an error code is returned that is not ATO_ERR_OK, the ato_Ctx object has an ato_Err object. This can be used to retrieve details on the last error that occurred including any nested errors. There is a separate Error API to retrieve details of the error.
The errorcode associated with an error object, and returned by many of the API methods, is an int. Given the nature of C, it is not possible to guarantee non-overlapping codes, so each errorcode returned should be interpreted in relation to the method called. For convenience, each self-contained API contains a list of non-overlapping errorcodes as "#defines". The ato_Err object does contain the library and module that raised the error, which provides more information if required.
All errors have an associated severity level - see ato_eErrSeverity. While the catagorisation of some errors with a given severity level is somewhat arbitrary, the table below gives a rational for the catagorisation.
Currently all errors are given a severity level of "ATO_ESEVERITY_WARN" (the default).
Error Severity | Implication | Action | Example causes |
ATO_ESEVERITY_FATAL | Panic | Halt (sometimes assertion) | Coding errors; environment errors: out of memory, disc corruption, missing mandatory configuration data |
ATO_ESEVERITY_ERR | Affects all processing - cannot process any messages/transactions until fixed | Warn user and go into RETRY until condition auto-corrects. If retry takes too long (or user cancels), escalate to FATAL | Infrastructure errors: cannot contact server |
ATO_ESEVERITY_WARN | Current msg/transaction cannot be processed. Others may be fine | Warn user and go into RETRY until condition auto-corrects. If retry takes too long (or user cancels), escalate to FATAL | Business rule violated for a given message or transaction: missing or bad data; incorrect user input such as bad password |
It is recommended that dependent SDKs wrap errors returned by ATOBASE with their own SDK specific error codes. This implies that ATOBASE errors are always inner/nested errors. In addition ATOBASE errors may wrap other ATOBASE errors. For ease of use it is also recommended that dependant SKDs have non-overlapping errcodes.
ATOBASE errcodes are of the form ATO_ERR_... where there is an associated an associated error object attached to he current context (contexts must be thread specific).
In addition, any error object can contain a custom error object which is interpreted according to an additional error API that knows how to interpret the custom error object. Currently the only custom error object is related to reporting network SOAP errors. This is the case if the errcode, of the containing general error object, is set to ATO_ERR_NET_SOAP.
While the default logger will automatically log errors (the application can override the default logger), it may be appropriate to interpret the errors further. The generic way of doing this is to iterate "down" through the inner errors and for each error check appropriate details and interpret any custom error.