A reason is a pointer to an additional data structure that provides information on causes for, and results of, actions taken by the user of ThisDN. If the Reasons attribute appears in the TEvent structure, it has been taken directly from the corresponding T-Library request.
There are times when the value of the Reasons attribute does not pertain to the most recent activity related to the DN or device in question. Such reasons are considered persistent or current. In particular, TQueryAddress and TRegisterAddress return the current reason for a DN. This allows applications such as Stat Server to retrieve the state of a DN, with its associated reason, at the time of startup or re-start and improves metrics quality and accuracy.
In any given instance, the value of the Reasons attribute is stored by T-Server in a TKVList. T-Server, however, does not control the context for this list. It therefore becomes the job of the application receiving this value as part of an event to interpret it appropriately. This is not always straightforward, since T-Server only preserves one reason for a given DN at any given time.
Additionally, T-Server only stores reasons that arrive from successful requests. Thus, if you receive an error in response to, for instance, an AgentNotReady request (because the agent or DN could not be set to the not ready state), the reason that you passed with the request is not preserved, and the reason from the previous successful request is still active.
To change a reason without changing the state of the agent or DN, you can send a request with a different reason several times. (This is supported for all 7.x T-Servers, by invoking the concept of self-transition states. Some older T-Servers may return errors.)