ParameterStyleRepCap::AddPhysicalNames

Adds one or more physical names to a repeated capability.

Syntax

static ViStatus AddPhysicalNames(ViSession Vi, const std::string& strSelector);

Parameters

Vi

[in] ViSession handle for the driver session.

strSelector

[in] A repeated capability selector which can include virtual names, physical names, comma-separated lists of names and physical name ranges.

Return value

Returns a VI_SUCCESS if the operation was successful or a failure ViStatus otherwise.

Remarks

The AddPhysicalNames function is used to add physical names to a repeated capability. This can be useful for drivers that support dynamic repeated capabilities — that is, repeated capabilities where the exact number of repeated capabilities is not known upfront. The driver can query the instrument to determine which physical names are present in the device and the driver can use the AddPhysicalNames function to add those names.

The strSelector parameter can include lists and ranges of physical names and is parsed and expanded according to the IVI-defined rules for repeated capability selectors, as presented in “IVI 3.1 Section 4.4.7 Formal Syntax for Repeated Capability Selectors”.

Selectors have a general form such as the following:

a1,a3,a5-a7:b2:[c5,c7]

Example

The following example demonstrates how a developer might query the instrument for physical names during the initialization sequence and use the results to populate a repeated capability using the AddPhysicalNames function.

ViStatus _VI_FUNC acme4321_InitWithOptions(ViRsrc ResourceName, ViBoolean IdQuery, ViBoolean Reset, ViConstString OptionsString, ViSession* Vi)
{
   auto status = VI_SUCCESS;

   status = nrt::InitWithOptions<Acme4321DriverSession>(ResourceName, IdQuery, Reset, OptionsString, Vi);
    ReturnOnError(status);

   if (Reset)
   {
       status = acme_reset(*Vi);
       ReturnOnError(status);
   }

   ReturnOnError(status);

   // Query the instrument for the number of channels
   //
   long cChannels;
   status = viQueryf(GetVisaSession(Vi), "SYST:CTYP:COUN?\n", "%lg%*t", &cChannels);
   ReturnOnError(status);

   // Note that the AddPhysicalNames function accepts selectors, so it can include ranges and comma-separated lists of
   // physical names.  Each channel name is of the form "CH[channel]".  We'll add all of the channels in one go by building
   // a selector that includes a range from 1 to the cChannels we queried from the device.
   //
   auto strSelector = "CH1-CH" + std::to_string(cChannels);
   status = Channel::AddPhysicalNames(Vi, strSelector);

   return status;
}