Ivi_SetAttributeViString
Usage
ViStatus Ivi_SetAttributeViString(ViSession vi, ViChar repeatedCapability[ ], ViAttr attributeID, ViInt32 optionFlags, ViChar attributeValue[ ]);
Purpose
This function sets the ViString attribute you specify to a new value. Depending on the configuration of the attribute, the function performs the following actions:
- Checks whether the attribute is writable. If not, the function returns an error.
- Validates the value you specify. If IVI_ATTR_RANGE_CHECK is enabled for the session and you provide a check callback for the attribute, the function invokes the check callback to validate the value. If the value is invalid, the function returns an error.
- Coerces the value you specify into a canonical value the instrument accepts. If you provide a coerce callback, the function invokes the callback to coerce the value.
- Compares the new value with the current cache value for the attribute to see if they are equal. When the cache value is a value the IVI engine obtained by querying the instrument and you provide a compare callback for the attribute, the function invokes the compare callback. Otherwise, the function makes the comparison based on strict equality.
- If the new value is not equal to the cache value or the cache value is invalid, the function invokes the write callback for the attribute. The write callback might perform I/O to send the value to the instrument. The IVI engine stores the new value in the cache. If the function coerces the value, the function caches the coerced value rather than the value you pass. The function allocates a copy of the string to keep in the cache.
- If the IVI_VAL_WAIT_FOR_OPC_AFTER_WRITES flag is set for the attribute, the function invokes the operation complete (OPC) callback you provide for the session.
- If you set the IVI_VAL_DIRECT_USER_CALL bit in the Option Flags parameter, the IVI_ATTR_QUERY_INSTRUMENT_STATUS attribute is enabled, and the IVI_VAL_DONT_CHECK_STATUS flag for the attribute is 0, then the function invokes the check status callback you provide for the session.
 |
Note If you set the IVI_VAL_SET_CACHE_ONLY bit in the Option Flags parameter, or if the IVI_ATTR_SIMULATE attribute is enabled and the IVI_VAL_USE_CALLBACKS_FOR_SIMULATION flag for the attribute is 0, the function does not call the write callback, the operation complete callback, or the check status callback. It merely updates the cache value of the attribute. |
Parameters
| Name | Type | Description |
|---|---|---|
| vi | ViSession |
Returns a ViSession handle that you use to identify the session in subsequent function calls. This function creates a new session each time you invoke it. This is useful if you have multiple physical instances of the same type of instrument. Avoid creating multiple concurrent sessions to the same physical instrument. Although you can create more than one IVI session for the same resource, it is best not to do so. A better approach is to use same session in multiple execution threads. You can use functions Ivi_LockSession and Ivi_UnlockSession to protect sections of code that require exclusive access to the resource. |
| repeatedCapability | ViChar[ ] |
If the attribute is repeated capability-based, specify a particular repeated capability. If the attribute you specify is not repeated capability-based, pass VI_NULL or an empty string. |
| attributeID | ViAttr |
Pass the ID of an attribute. If you want to enter the ID of a class or specific driver attribute, press If you want to enter the ID of an IVI attribute, then you can use this control as a ring control. When you click on this ring control or press <ENTER>, <SPACEBAR>, or <CTRL-DOWN>, a dialog box appears containing a hierarchical list of the attributes the IVI engine defines. The dialog shows help text for each attribute. When you select an attribute by double-clicking on it or by highlighting it and then pressing <ENTER>, the dialog disappears and your choice appears in this function panel control. If this function is a SetAttribute or CheckAttribute function, read-only attributes appear dim in the list box. If you select a read-only an attribute, an error message appears. A ring control at the top of the dialog box allows you to see all IVI attributes or only the attributes that have data types consistent with this function. If you choose to see all IVI attributes, the data types appear to the right of the attribute names in the list box. The data types that are not consistent with this function are dim. If you select an attribute data type that is dim, LabWindows/CVI transfers you to the function panel for the corresponding function that is consistent with the data type. If the attribute in this ring control has named constants as valid values, you can bring up a list of them by moving to the Attribute Value control and pressing <ENTER>. |
| optionFlags | ViInt32 |
Use this parameter to request special behavior. In most cases, you pass 0. You can specify individual bits to request specific behavior. Each of the following sections describes one of the bit values. IVI_VAL_DIRECT_USER_CALL (1<<0)Use the IVI_VAL_DIRECT_USER_CALL bit when calling this function from the source code for the PREFIX_Set/Get/CheckAttribute functions that your instrument driver exports. Do not use the bit when calling this function from any other context. If you set this bit, this function checks the IVI_VAL_USER_READABLE or IVI_VAL_USER_WRITABLE flag. If the end-user does not have permission to access the attribute, the function returns an error. If you set this bit, the function also checks the status of the instrument after invoking the read or write callback for the attribute, but only if the following conditions are true.
IVI_VAL_SET_CACHE_ONLY (1<<1)This bit applies only to calls that specific instrument drivers make to the Ivi_SetAttribute functions. Pass 1 for this bit if want to set the value in the attribute cache but you do not want to invoke the write callback for the attribute. This is useful if one instrument I/O command sets multiple attributes in the instrument. In the write callback function that performs the instrument I/O, after the instrument I/O succeeds, call an Ivi_SetAttribute function for each of the other attributes, with set the IVI_VAL_SET_CACHE_ONLY bit set to 1 in the Option Flags parameter. IVI_VAL_DONT_MARK_AS_SET_BY_USER (1<<2)This bit applies only to calls that specific instrument drivers make to the Ivi_SetAttribute functions. Pass 1 for this bit if want to set an attribute value even though the user has not requested you to do so directly through a PREFIX_SetAttribute function call or indirectly through a helper function that sets multiple attributes. This case occurs very rarely. It affects interchangeability checking in class drivers. To pass interchangeability checking, either all attributes in an extension group must be marked as "set by user" or none of them must be marked as "set by user". |
| attributeValue | ViChar[ ] |
Pass the value to which you want to set the attribute. If the attribute currently showing in the Attribute ID ring control has named constants as valid values, you can bring up a list of them on this control by pressing ENTER. Select a value by double-clicking on it or by highlighting it and then pressing ENTER. Some of the values might not be valid depending on the current settings of the instrument session. |
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.