Ivi_GetAttributeViSession
Usage
ViStatus Ivi_GetAttributeViSession(ViSession vi, ViChar repeatedCapability[ ], ViAttr attributeID, ViInt32 optionFlags, ViSession* attributeValue);
Purpose
This function obtains the current value of the ViSession attribute you specify. Depending on the configuration of the attribute, the function performs the following actions:
- Checks whether the attribute is readable. If not, the function returns an error.
- If the attribute cache value is currently valid, the read callback for the attribute is VI_NULL, or the IVI_ATTR_SIMULATE attribute is enabled and the IVI_ATTR_USE_CALLBACKS_FOR_SIMULATION flag for the attribute is 0, the function returns the cache value.
- If the IVI_VAL_WAIT_FOR_OPC_BEFORE_READS flag is set for the attribute, the function invokes the operation complete (OPC) callback you provide for the session.
- The function invokes the read callback for the attribute. Typically, the callback performs instrument I/O to obtain a new value. The IVI engine stores the new value in the cache.
- 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.
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 | ViSession* |
Returns the current value of the attribute. Pass the address of a ViSession variable. 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>. |
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.