Knowledge Center

Status and State

Many entities provide state and/or status information. State/Status uses a pull model with developers setting up a poll to retrieve data from the server. We’ll look at some patterns for status and how to use some of the information found.

State

Entities that support NA_Commanding provide simple state support. Many entities support this interface and provide a state string with what they are currently doing. For instance,

• Recorder – might be Recording, Stopped, Paused, etc.
• Data Flow – might be Running, Stopped, etc.
• Serial Channel – might be Locked, Flywheeling, No Data, etc.

NA_Commanding dfe0Cmd = server.GetCommanding("device/dfe/0");
string state = dfe0Cmd.GetEntityState();

if (state.Contains("Running"))
{
    // do things...
}

Sometimes state can be complex, as is the case with the time entity.

NA_Commanding timeCmd = server.GetCommanding("dispatch/p_time");
string state = timeCmd.GetEntityState();

// The p_time entity returns strings of the form
// (seconds) (microseconds) (client status) (server status)
// Examples:

// 1320699996 950997 Client:Time Conditioner reports: Nominal -  (Internal Real Time Clock) Server: SNTP Not Started; PTP Not Started

// 1320699518 253669 Client:Time Conditioner reports: Nominal -  offset -0.017299 sec  slew 0.9946  (Sntp Accurate time) Server: SNTP Not Started; PTP Not Started

// 1320711082 966024 Client:Time Conditioner reports: Nominal -  offset -0.000081 sec  slew 0.9982  (IRIG No Signal) Server: SNTP Not Started; PTP Not Started

Status

Status uses a pair of calls to determine ‘current’ status. An array of descriptors refers to an array of status using a generation value as a key. The notion is to fetch descriptors, then poll for status, passing along the generation of your last-retrieved descriptors. If a mismatch occurs, a “bad generation” exception occurs and you start over by fetching the new descriptors.

The rolling of the generation ensures that, on a reconfiguration (or restart) of some entity, the descriptors are refreshed. Some entities support changing the status they provide based on how they are configured and the generation changing tells the client it’s time to update.

Channel and Stream

When fetching status, we reference the parent entity (or channel), such as the serial instance (sio/0), then the stream we’re interested in, which might be channel 3. In UNC parlance, that would be sio/0/3.

Let’s look at a code example.

// fetch the status entity for serial 0
NA_DynamicStatus status = server.GetDynamicStatus("sio/0");

Common Polling Pattern

Let’s look at a general pattern that avoids an up-front call to get descriptors, simplifying the overall code.

NA_StatusDescription[] descriptors = { };
NA_StatusValue[] values = { };

// pick an unlikely target generation
int generation = -36754735;

for (int i = 0; i < 10; i ++)
{
    try
    {
        // get the values for our generation
        values = status.GetStatusValues(3, generation);

        // simple sleep for example
        System.Threading.Thread.Sleep(250);
    }
    catch (NA_WrongGeneration wrongGen)
    {
        // generation is no good, get new descriptors
        descriptors = status.GetStatusDescriptions(3, out generation);
    }
}

Names

Before we look at how to address the values, let’s talk about how to identify the values. The best way to know what’s likely in the value array is to use the Dynamic Status page’s Advanced view. The column headers report the descriptor Name verbatim. For instance, data flows might report,

Data Types

Now that we have some values, how do operate on them? The descriptor and value arrays map index-to-index, with the descriptor telling you about the value.

Descriptor

• Name – as above, these names are the column headers. You can search based on these strings. This value combines with Direction to provide a unique key
• Type – the data type, one of
  • Unsigned32Type
  • Integer32Type
  • Integer64Type
  • DoubleType
  • StringType
  • IndicatorType
• Direction – [In, Out, None] this value combines with Name to provide a unique key, for instance a serial channel has a Status field for both In and Out, aka Rx and Tx.
• SupportsReset – a Boolean indicating if programmatic reset of the value is supported

Value

• Type – (aka the Discriminator) the data type, same as a descriptor
• Various getter methods to retrieve the value.

The discriminator (type) informs which getter method you should use to fetch the value. Developers familiar with discriminated unions should recognize this type of pattern.

Use the same-indexed descriptor to find the meta-data about the value.

Indicators

The data type NA_StatusIndicator represents a complex value that combines a string (Description) and a color.