Ivi_GetNextCoercionInfo
Usage
ViStatus Ivi_GetNextCoercionInfo(ViSession vi, ViAttr* attributeID, ViConstString* attributeName, ViConstString* repeatedCapabilityname, IviValueType* attributeDataType, ViReal64* desiredValue, ViReal64* coercedValue);
Purpose
This function obtains information regarding the oldest instance in which the IVI engine coerced an attribute value you specified to another value. It then deletes that information.
If you enable the IVI_ATTR_RECORD_COERCIONS attribute for the session, the IVI engine keeps a list of all coercions it makes on values you pass to an Ivi_SetAttribute function for a ViInt32 or ViReal64 attribute. You can use this function to retrieve information from that list. Each time you call this function, it extracts and deletes the oldest coercion record for the session.
When no coercion records remain for the session, the function returns IVI_ATTR_NONE (-1) in the Attribute ID parameter and VI_NULL in the Attribute Name parameter.
The function returns all numeric values as ViReal64 values, even for ViInt32 attributes.
You can pass VI_NULL for any of the output parameters, except that you cannot pass VI_NULL for both the Attribute ID and Attribute Name parameters in one call.
Parameters
| Name | Type | Description | ||||||
|---|---|---|---|---|---|---|---|---|
| vi | ViSession |
The ViSession handle that you obtain from Ivi_SpecificDriverNew. The handle identifies a particular IVI session. |
||||||
| attributeID | ViAttr* |
Returns the ID of the attribute for which the value coercion occurred. No more coercion records exist for session, this parameter returns IVI_ATTR_NONE (-1). If you are not interested in this value, you can pass VI_NULL as long as you do not also pass VI_NULL for the Attribute Name parameter. |
||||||
| attributeName | ViConstString* |
Returns a pointer to the name of the attribute for which the value coercion occurred. If no more coercion records exist for session, this parameter returns VI_NULL. Do not modify the contents of the name. If you are not interested in this value, you can pass VI_NULL as long as you do not also pass VI_NULL for the Attribute ID parameter. |
||||||
| repeatedCapabilityname | ViConstString* |
If the attribute is repeated capability-based, this parameter returns a pointer to the name of the repeated capability on which the value coercion occurred. If the attribute is not repeated capability-based, this parameter returns a pointer to an empty string. Do not modify the contents of the repeated capability string. If you are not interested in this value, you can pass VI_NULL. |
||||||
| attributeDataType | IviValueType* |
Returns the data type of the attribute. Values:
If you are not interested in this value, you can pass VI_NULL. |
||||||
| desiredValue | ViReal64* |
Returns the value to which you attempted to set the attribute. The function always returns the value as a ViReal64 value, even if the data type of the attribute is ViInt32. If you are not interested in this value, you can pass VI_NULL. |
||||||
| coercedValue | ViReal64* |
Returns the value to which the IVI engine actually set the attribute. The function always returns the value as a ViReal64 value, even if the data type of the attribute is ViInt32. If you are not interested in this value, you can pass VI_NULL. |
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.