Ivi_SetAttributeViReal64

Usage

ViStatus Ivi_SetAttributeViReal64(ViSession vi, ViChar repeatedCapability[ ], ViAttr attributeID, ViInt32 optionFlags, ViReal64 attributeValue[ ]);

Purpose

This function sets the ViReal64 attribute you specify to a new value. Depending on the configuration of the attribute, the function performs the following actions:

1. Checks whether the attribute is writable. If not, the function returns an error.
2. Validates the value you specify if IVI_ATTR_RANGE_CHECK is enabled for the session. If you provide a check callback, the function invokes the callback to validate the value. If you do not provide a check callback but you provide a range table or a range table callback, the function invokes the default IVI check callback to validate the value. If the value is invalid, the function returns an error.
3. 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. If you do not provide a coerce callback but you provide a coerced range table directly or through a range table callback, the function invokes the default IVI coerce callback to coerce the value.
4. Compares the new value with the current cache value for the attribute to see if they are equal. The method it uses depends on the source of the cache value. If the cache contains a value you previously sent to the instrument using this function, the function compares the two values using strict equality. If the cache contains a value you obtained from the instrument using Ivi_GetAttributeViReal64, the function invokes the compare callback you provide for the attribute or the default IVI compare callback, which uses the comparison precision you specify when you create the attribute.
5. 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.
6. 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.
7. 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	The ViSession handle that you obtain from Ivi_SpecificDriverNew. The handle identifies a particular IVI session.
repeatedCapability	ViChar[ ]	If the attribute you specify is based on a repeated capability, pass a repeated capability identifier. You can pass one of the identifiers strings that the specific instrument driver defines, or a virtual name the end-user defines in the configuration file. If the attribute you specify is not based on a repeated capability, 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 to toggle this ring control to the manual input box so you can type the ID constant. 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. This is a SetAttribute or GetAttribute function. The value of the IVI_ATTR_QUERY_INSTRUMENT_STATUS attribute for the session is VI_TRUE. The value of the IVI_VAL_DONT_CHECK_STATUS flag for the attribute is 0. 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	ViReal64	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

This function sets the ViReal64 attribute you specify to a new value. Depending on the configuration of the attribute, the function performs the following actions:

1. Checks whether the attribute is writable. If not, the function returns an error.
2. Validates the value you specify if IVI_ATTR_RANGE_CHECK is enabled for the session. If you provide a check callback, the function invokes the callback to validate the value. If you do not provide a check callback but you provide a range table or a range table callback, the function invokes the default IVI check callback to validate the value. If the value is invalid, the function returns an error.
3. 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. If you do not provide a coerce callback but you provide a coerced range table directly or through a range table callback, the function invokes the default IVI coerce callback to coerce the value.
4. Compares the new value with the current cache value for the attribute to see if they are equal. The method it uses depends on the source of the cache value. If the cache contains a value you previously sent to the instrument using this function, the function compares the two values using strict equality. If the cache contains a value you obtained from the instrument using Ivi_GetAttributeViReal64, the function invokes the compare callback you provide for the attribute or the default IVI compare callback, which uses the comparison precision you specify when you create the attribute.
5. 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.
6. 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.
7. 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.

Related Topic

IVI Status Codes