Ivi_CoerceRepCapName
Usage
ViStatus Ivi_CoerceRepCapName(ViSession vi, ViChar repeatedCapabilityName[ ], ViChar repeatedCapabilityIdentifier[ ], ViConstString* repeatedCapabilityString);
Purpose
This function verifies that the Repeated Capability Name parameter you pass is valid and returns a pointer to the corresponding specific driver repeated capability string in the Repeated Capability String output parameter.
If your driver supports multiple repeated capability instances, you must call Ivi_CoerceRepCapName in driver functions that use the string directly. When you call an Ivi_SetAttribute, Ivi_GetAttribute, or Ivi_CheckAttribute function, the IVI engine coerces the name internally before invoking the read, write, check, coerce, compare, and range table callback functions.
To be valid, Repeated Capability Name must be one of the following:
- VI_NULL, in which case the function sets the Repeated Capability String parameter to VI_NULL.
- An empty string, in which case the function returns the address of that empty string in the Repeated Capability String parameter.
- A specific driver repeated capability string. The specific instrument driver specifies the valid repeated capability strings using Ivi_BuildRepCapTable or Ivi_AddToRepCapTable. If you pass one of these strings, the function returns the address of the repeated capability string in the repeated capability table that the IVI engine maintains for the session.
- A virtual repeated capability name that the end-user specifies in the configuration file. Virtual repeated capability names are valid only if the the end-user opens the session from a class driver and assigns a valid specific driver repeated capability string to the virtual name in the configuration file. If you pass a valid virtual name to this function, the function returns the address of the corresponding specific driver repeated capability string in the repeated capability table that the IVI engine maintains for the session.
Parameters
| Name | Type | Description |
|---|---|---|
| vi | ViSession |
The ViSession handle that you obtain from Ivi_SpecificDriverNew. The handle identifies a particular IVI session. |
| repeatedCapabilityName | ViChar[ ] |
Pass a string containing the name of the repeated capability on which to operate. For instance, if you are working with the table of channel names, pass in the string "Channel". |
| repeatedCapabilityIdentifier | ViChar[ ] |
Pass the repeated capability name that you want to verify and convert to a specific driver repeated capability string. Usually, this is the string that the end-user passes into a specific driver function. The parameter accepts VI_NULL, an empty string, a specific driver-defined repeated capability identifier, or a virtual repeated capability identifier. |
| repeatedCapabilityString | ViConstString* |
Returns a pointer to a repeated capability identifier string in the repeated capability table that the IVI engine maintains for the session. Do not modify the contents of the repeated capability string. If you pass VI_NULL in the Repeated Capability Identifier parameter, the function returns VI_NULL in this parameter. If you pass an empty string, the function returns the address of the empty string. |
Return Value
Contains the status code that the function call returns. IVI engine functions can return error and warning values from several sets of status codes. Some status codes are unique to the IVI engine. Other status codes are the same codes that VISA Library functions return. Still others are error or warning values that functions in specific instrument drivers return. Each set of status codes has its own numeric range.
Regardless of the source of the status code, 0 always indicates success, a positive value indicates a warning, and a negative value indicates an error.