Ivi_AddAttributeInvalidation
Usage
ViStatus Ivi_AddAttributeInvalidation(ViSession vi, ViAttr attributeID, ViAttr dependentAttributeID, ViBoolean allInstances);
Purpose
This function creates an invalidation dependency relationship between two attributes. When you set the first attribute to a new value, the IVI engine marks the cache value for the second attribute value as invalid. When an attribute cache value is invalid, any attempt to obtain or change the current value of the attribute causes the IVI engine to invoke the read or write callback function for the attribute regardless of the cache value.
Create a dependency relationship if setting the value of one attribute can cause the value of another attribute to change or become out-of-range in the instrument. When this occurs, the cache value of the second attribute no longer reflects the true state of the instrument.
Two-Way Invalidations
Although you can create a two-way invalidation dependency relationship between attributes, it is rarely the correct thing to do. Cases can occur where changing one instrument setting affects another instrument setting, and changing the second instrument setting affects the first. The proper way to handle this situation is to impose a one-way invalidation model in the instrument driver. Identify one attribute as dominant and the other as dependent. Call Ivi_AddAttributeInvalidation to notify the IVI engine that changing the value of the dominant attribute invalidates the dependent attribute. Range check values for the dependent attribute based on the current setting of the dominant attribute. Do not allow the end-user to set the dependent attribute to a value that would cause the instrument to modify the setting of the dominant attribute.
Parameters
| Name | Type | Description |
|---|---|---|
| vi | ViSession | The ViSession handle that you obtain from Ivi_SpecificDriverNew. The handle identifies a particular IVI session. |
| attributeID | ViAttr | Pass the ID of the attribute for which a change in value can render the cache value of the second attribute unreliable. |
| dependentAttributeID | ViAttr | Pass the ID of the attribute to invalidate when the value of the first attribute changes. |
| allInstances | ViBoolean |
Specify whether the invalidation occurs on all possible repeated capability instances or only on the instance on which the value of the first attribute changes. This option is relevant only if both attributes are based on the same repeated capability. Pass VI_TRUE (1) if you want the invalidation to occur on all repeated capability instances. Otherwise, pass VI_FALSE (0). |
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.