niRFSG_GetAttributeViString
C Function Prototype
ViStatus niRFSG_GetAttributeViString (ViSession vi, ViConstString channelName, ViAttr attributeID, ViInt32 bufferSize, ViChar[] attributeValue);
Purpose
Queries the value of a ViString attribute.
Use this low-level function to get the values of inherent IVI attributes, class-defined attributes, and instrument-specific attributes. If the attribute represents an instrument state, this function performs instrument I/O in the following cases:
- State caching is disabled for the entire session or for the particular attribute.
- State caching is enabled, and the currently cached value is invalid.
You must provide a ViString (ViChar array) to serve as a buffer for the value. Pass the number of bytes in the buffer as the Buffer Size parameter. If the current value of the attribute, including the terminating NULL 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 NULL 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.
To call this function to get only the required buffer size, pass 0 for the buffer size and VI_NULL for the attribute value buffer.
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 bufferSize parameter.
Parameters
| Input | ||
| Name | Type | Description |
| vi | ViSession | Identifies your instrument session. The ViSession handle is obtained from the niRFSG_init function or the niRFSG_InitWithOptions function and identifies a particular instrument session. Default Value: None |
| channelName | ViConstString | Specifies the channel to which the attribute applies if this attribute is channel-based. If the attribute is not channel-based, set this parameter to "" (empty string) or VI_NULL. Default Value: "" (empty string) |
| attributeID | ViAttr | Pass the ID of an attribute. |
| bufferSize | ViInt32 | Pass the number of bytes in the ViChar buffer you specify for the attributeValue parameter. 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 attributeValue parameter. |
| Output | ||
| Name | Type | Description |
| 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 bufferSize parameter. If you specify 0 for the bufferSize parameter, you can pass VI_NULL for this parameter. |
Return Value
| Name | Type | Description |
| status | ViStatus |