Reasons

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.

Warning

There is no other source for the information found in the content of the Reasons attribute. Media device/hardware reason codes, and similar information, do not appear in the Reasons attribute. Rather, if they are supported, those hardware reasons are provided by T-Server in the Extensions attribute. The figure below diagrams the difference between media-device reasons and the Reasons attribute (Genesys Reasons).

Genesys Reasons versus Media-Device Reasons

Persistent Reasons

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.

Important

In order to erase a reason completely, applications need to pass an empty TKVList in a request (and receive successful confirmation). Requests with NULL as the reason do not affect the current reason. (This is done to preserve backward compatibility.)

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

Important

A T-Server synchronizes its Reasons attributes with its backup for use in failover. But there is no resynchronization of these attributes at the time of a backup T-Server's reconnection.