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 Driver Settings Editor.

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 function. One may accurately think of GetDynamicRepCapNames as the programmatic equivalent of the repeated capabilities Driver Settings Editor. The driver developer overrides this function in the main driver class header file and provides whatever logic necessary to return a list of repeated capability names. Nimbus automatically invokes the overridden GetDynamicRepCapNames function during driver initialization.

The signature of the GetDynamicRepCapNames function is as follows:

virtual HRESULT GetDynamicRepCapNames(const CString& repCapClassName, CAtlArray<CString>& rgRepCapNames);

The repCapClassName parameter is passed to the function by Nimbus and represents the repeated capability class for which you should return the associated repeated capability names.

The rgRepCapNames parameter is an array that the function implementation should use to return the dynamic repeated capability names to Nimbus. Nimbus will create one instance of the repeated capability class identified by the repCapClassName parameter for each element added to the rgRepCapNames array.

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

// CoAcme4321.h
class ATL_NO_VTABLE Acme4321 : 
{
   // ...

   virtual HRESULT GetDynamicRepCapNames(const CString& repCapClassName, CAtlArray<CString>& rgRepCapNames)
   {
      if (repCapClassName == _T("Acme4321InputChannel"))
      {
         // Query the instrument for the number of digital input cards plugged into the mainframe
         long lNumCards;
         hr = InstrQueryf(_T("SYST:CTYP:COUN?", &lNumCards));
         if (FAILED(hr)) return hr;

         // Each card has 32 input channels
         for (int lSlot = 0; lSlot < lNumCards; lSlot++)
         {
            for (int lChannel = 0; lChannel < 32; lChannel++)
            {
               // Each channel name will be of the form: "Channel-[slot]-[channel]"
               CString strName;
               strName.Format(_T("Channel-%d-%d"), lSlot, lChannel);

               // Add the name to the collection of repeated capability names
               rgRepCapNames.Add(strName);
            }
         }
      }
      else if (repCapClassName == _T("Acme4321OutputChannel"))
      {
         // ... query instrument for the number of dynamic trace repeated capabilities
      }
   }

   // ...
}

Other Resources