WissDB . since Jun 15 . Index . DOCs TOP TOC

R_ Requirements on DL_API API Implementation

Each call of one of the services (= functions) specified in the following is to guarantee that the value of the B_WissDB_Database remains unchanged if the ReturnCode value is neither RC_ok nor RC_seeWarnings.

Another important requirement on these services is that they must be powerful enough to implement C_WissDB_API in a painless way.

Each service is specified with two specific output parameters called AppErrors and ReturnCode:

§      Out: AppErrors

§      Out: ReturnCode is one of the following values:

–      RC_ok

–      RC_syserror

–      RC_seeAppErrors

Depending on the programming langue used, these two parameters may be implemented quite differently. In Java, e.g. at least RC_syserror would best be implemented in form of a runtime exception, whereas RC_seeAppErrors might be implemented differently from case to case:

§      If an exception such as ObjectNotFound is enough error description, to throw an exception implementing both the returncode RC_seeAppErrors and also the AppErrors would be fine (and should be preferred). 

§      If however syntax errors (or logical errors hard to explain) are detected somewhere, the AppErrors need to be a dynamically generated text the application could then write to either a file or the console.

A value of type AppErrors is a string containing one or more text sections of the form

AppError in S_x : ErrorType: Diagnostic data

or

Warning out of S_x : any text

such that S_x is the service activated by an application of the DL_API API (it must not be the name of an auxiliary method that is part of the hidden implementation of this service: applications are to see the system they use as a black box).

The service is to return RC_seeAppErrors if and only if parameter AppErrors is describing at least one AppError.

The service should describe as many AppErrors as possible before returning.