DDS11 — Need an extra return code: ILLEGAL_OPERATION

It would be useful to have an additional return code called RETCODE_ILLEGAL_OPERATION. This return code would be useful, for example, in preventing the user from performing certain operations on the built-in DataReaders. Their QoS values are stated in the specification; vendors need not allow those values to be changed. Users should also not be allowed to delete built-in Entities. If the user tries to perform either of these two operations, the choices of return code we could use that are in accordance to the spec are:
· RETCODE_ERROR
· RETCODE_UNSUPPORTED
· RETCODE_BAD_PARAMETER
· RETCODE_PRECONDITION_NOT_MET
· RETCODE_IMMUTABLE_POLICY

All of the above fall short of helping the user find out what the problem really is.
· RETCODE_ERROR: This is the generic error code; it does not give much information as to what might be wrong.
· RETCODE_UNSUPPORTED: This choice would be semantically incorrect. The failure is not due to a vendor's failure to support an optional feature of the specification, but rather to the user's violation of a policy consistent with the specification that was set by that vendor.
· RETCODE_BAD_PARAMETER: This return code is a little confusing. For instance, when trying to delete a built-in DataReader, the reader parameter passed is a valid DataReader and the function is expecting a reader. Such usage would seem to constitute passing a good parameter, not a bad one.
· RETCODE_PRECONDITION_NOT_MET: There is no precondition that the user could change that would make the call work. Therefore, this result would be confusing.
· RETCODE_IMMUTABLE_POLICY: This return code could potentially work when trying to change the QoS policies of the built-in DataReaders but not when attempting to delete them. However, it would still be semantically incorrect. The problem is not that the user is trying to change immutable QoS policies.

The QoS policies being changed may be mutable; what is not allowed is the Entity whose policies are in question. Such a return result could lead the user to think that s/he is confused about which QoS policies are mutable.

Proposed Resolution:
Add a return code RETCODE_ILLEGAL_OPERATION. This return code indicates a misuse of the API provided by the Service. The user is invoking an operation on an inappropriate Entity or at an inappropriate time. There is no precondition that could be changed to allow the operation to succeed.
Vendors may use this new return code to indicate violations of policies they have set that are consistent with, but not fully described by, the specification. It is therefore necessary that the return code be considered a "standard" return code (like RETCODE_OK, RETCODE_BAD_PARAMETER, and RETCODE_ERROR) that could potentially be returned by any operation having the return type ReturnCode_t.

Proposed Revised Text:
Add the following row to the "Return codes" table in 2.1.1.1:
ILLEGAL_OPERATION An operation was invoked on an inappropriate object or at an inappropriate time (as determined by policies set by the specification or the Service implementation). There is no precondition that could be changed to make the operation succeed.

In the paragraph following the table, the sentence "Any operation with return type ReturnCode_t may return OK or ERROR" should be restated "Any operation with return type ReturnCode_t may return OK, ERROR, or ILLEGAL_OPERATION." The sentence "The return codes OK, ERROR, ALREADY_DELETED, UNSUPPORTED, and BAD_PARAMETER are the standard return codes and the specification won't mention them explicitly for each operation" should be restated as "The return codes OK, ERROR, ILLEGAL_OPERATION, ALREADY_DELETED, UNSUPPORTED, and BAD_PARAMETER are the standard return codes and the specification won't mention them explicitly for each operation".

No Data Available