Ivi_GetAttributeViString
Usage
ViStatus Ivi_GetAttributeViString(ViSession vi, ViChar repeatedCapability[ ], ViAttr attributeID, ViInt32 optionFlags, ViInt32 bufferSize, ViChar attributeValue[ ]);
Purpose
This function obtains the current value of the ViString attribute you specify.
You must provide a ViChar array to serve as a buffer for the value. You pass the number of bytes in the buffer as the Buffer Size parameter. If the current value of the attribute, including the terminating NUL byte, is larger than the size you indicate in the Buffer Size parameter, the function copies Buffer Size - 1 bytes into the buffer, places an ASCII NUL byte at the end of the buffer, and returns the buffer size you must pass to get the entire value. For example, if the value is "123456" and the Buffer Size is 4, the function places "123" into the buffer and returns 7.
If you want the function to fill in the buffer regardless of the number of bytes in the value, pass a negative number for the Buffer Size parameter. If you want to call this function just to get the required buffer size, you can pass 0 for the Buffer Size and VI_NULL for the Attribute Value buffer.
Remember that the checkErr and viCheckErr macros ignore positive return values. If you use one of these macros around a call to this function, you lose the required buffer size when the function returns it. To retain this information, declare a separate local variable to store the required buffer size, and use the macro around the assignment of the return value to the local variable. The following is an example:
ViStatus error = VI_SUCCESS;ViInt32 requiredBufferSize;
checkErr( requiredBufferSize =
Ivi_GetAttributeViString(vi, channel, attr, 0, 0, VI_NULL));
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". |
| bufferSize | ViInt32 |
Pass the number of bytes in the ViChar array you specify for the Attribute Value parameter. If the current value of the attribute, including the terminating NUL byte, contains more bytes that you indicate in this parameter, the function copies Buffer Size - 1 bytes into the buffer, places an ASCII NUL byte at the end of the buffer, and returns the buffer size you must pass to get the entire value. For example, if the value is "123456" and the Buffer Size is 4, the function places "123" into the buffer and returns 7. If you pass a negative number, the function copies the value to the buffer regardless of the number of bytes in the value. If you pass 0, you can pass VI_NULL for the Attribute Value buffer parameter. |
| attributeValue | ViChar[ ] |
The buffer in which the function returns the current value of the attribute. The buffer must be of type ViChar and have at least as many bytes as indicated in the Buffer Size parameter. If the current value of the attribute, including the terminating NUL byte, contains more bytes that you indicate in this parameter, the function copies Buffer Size - 1 bytes into the buffer, places an ASCII NUL byte at the end of the buffer, and returns the buffer size you must pass to get the entire value. For example, if the value is "123456" and the Buffer Size is 4, the function places "123" into the buffer and returns 7. If you specify 0 for the Buffer Size parameter, you can pass VI_NULL for this parameter. 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.
If the function succeeds and the buffer you pass is large enough to hold the entire value, the function returns 0.
If the current value of the attribute, including the terminating NUL byte, is larger than the size you indicate in the Buffer Size parameter, the function copies Buffer Size - 1 bytes into the buffer, places an ASCII NUL byte at the end of the buffer, and returns the buffer size you must pass to get the entire value. For example, if the value is "123456" and the Buffer Size is 4, the function places "123" into the buffer and returns 7.
If the function fails for some other reason, it returns a negative error code. For more information on error codes, refer to the Status return value control in one of the other function panels.