Click or drag to resize

Implementing Dynamic Repeated Capabilities

Nimbus supports two types of repeated capabilities -- static repeated capabilities and dynamic repeated capabilities. Static repeated capabilities represent the fixed functionality of the instrument -- such as physical channels on an oscilloscope. These repeated capabilities must be configured at driver development time using the Properties Window for the repeated capability in question.

Dynamic repeated capabilities are those that cannot be determined at driver development time. Rather, the driver must "discover" by communicating with the instrument what repeated capabilities are present. For example, a driver for a multi-slot digital I/O mainframe has no way to know at driver development time what type and number of digital I/O cards will be plugged into the available mainframe slots.

In order to support dynamic repeated capabilities, Nimbus provides the GetDynamicRepCapNames(String, IListString) method. One may accurately think of GetDynamicRepCapNames(String, IListString) method as the programmatic equivalent of the repeated capabilities Properties Window. The driver developer overrides this function in the appropriate class and provides whatever logic necessary to return a list of repeated capability names. Nimbus automatically invokes the overridden GetDynamicRepCapNames function during driver execution of the driver constructor.

The signature of the GetDynamicRepCapNames function is as follows:

C#
protected virtual void GetDynamicRepCapNames(string repCapName, IList<string> physicalNames)

The repCapName parameter is passed to the function by Nimbus and represents the repeated capability name for which you should return the associated physical names for the repeated capability instances that Nimbus should created.

The physicalNames parameter is a list that the method implementation should use to return the dynamic repeated capability names to Nimbus. Nimbus will create one instance of the repeated capability class associated with the identified by the repCapName parameter for each element added to the physicalNames list.

The class on which GetDynamicRepCapNames function is implemented depends upon the repeated capability style (collection-style, parameter-style, or selector-style) and whether or not the repeated capability is nested. For a collection-style repeated capability, the GetDynamicRepCapNames function must be overridden on the corresponding collection class (e.g. Acme4321ChannelCollection). This is true irrespective of whether or not the collection-style repeated capability is nested (i.e. has a parent repeated capability). For parameter-style and selector-style repeated capabilities, the GetDynamicRepCapNames function must be overridden on the parent class. For non-nested parameter-style or selector-style repeated capabilities, the parent class will be the main driver class (e.g. Acme4321). If a parameter-style repeated capability has any parent collection-style repeated capability, then the override of GetDynamicRepCapNames function for that parameter style repeated capability must appear on the parent repeated capability class (e.g. Acme4321Channel).

Nimbus invokes the GetDynamicRepCapNames function only once for each non-nested repeated capability. For nested repeated capabilities, Nimbus first invokes the GetDynamicRepCapNames function for the parent repeated capability, thereby gathering and creating all instances of that parent repeated capability. Then, for each parent repeated capability instance, Nimbus invokes the GetDynamicRepCapNames function for the child repeated capability. For example, consider a collection-style "Channel" repeated capability with a child "Trace" parameter-style repeated capability. The three driver classes are Acme4321 (the main driver class), Acme4321ChannelCollection (the channel collection class), and Acme4321Channel (the channel repeated capability class). During initialization of the driver, Nimbus will invoke the GetDynamicRepCapNames function on the Acme4321ChannelCollection class (passing in "Channel" as the repeated capability name). Assume the implementation returns the names "Channel1", "Channel2", and "Channel3". This results in the construction of three instances of the Acme4321Channel class. Next, Nimbus will invoke the GetDynamicRepCapNames function (passing in "Trace" as the repeated capability name) on the Acme4321Channel class three times -- once for each of the three instances of the parent Acme4321Channel.

The code below demonstrates how to implement GetDynamicRepCapNames in the main driver class.

C#
// Acme4321InputChannelCollection.cs
public sealed class class Acme4321InputChannelCollection : RepCapCollection<Acme4321InputChannel>,
        IAcme4321InputChannelCollection
   // ...
{
   // ...

   protected override void GetDynamicRepCapNames(string repCapName, IList<string> physicalNames)
   {
      if (repCapName == _T("InputChannel"))
      {
         // Query the instrument for the number of digital input cards plugged into the mainframe
         this.IO.FormattedIO.WriteLine("SYST:CTYP:COUN?");
         var cardCount = this.IO.FormattedIO.ReadLineInt64();

         // Each card has 32 input channels
         for (int slot = 0; slot < cardCount; slot++)
         {
            for (int channel = 0; channel < 32; channel++)
            {
               // Each channel name will be of the form: "Channel-[slot]-[channel]"
               var name = String.Format("Channel-{0}-{1}"), slot, channel);

               // Add the name to the collection of repeated capability names
               physicalNames.Add(name);
            }
         }
      }
   }

   // ...
}
See Also

Download a complete CHM version of this documentation here.