Ivi_CheckAttributeViString
Usage
ViStatus Ivi_CheckAttributeViString(ViSession vi, ViChar repeatedCapability[ ], ViAttr attributeID, ViInt32 optionFlags, ViChar attributeValue[ ]);
Purpose
This function checks the validity of a value you specify for a ViString 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 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. If the attribute has no check callback, the function assumes the value is valid.
Parameters
| Name | Type | Description |
|---|---|---|
| vi | ViSession |
The ViSession handle that you obtain from Ivi_SpecificDriverNew. The handle identifies a particular IVI session. |
| 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 which you want to verify as a valid value for the attribute given the current settings of the instrument session. 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.