niFgen_GetAttributeViString
ViStatus niFgen_GetAttributeViString (ViSession vi, ViConstString channelName, ViAttr attributeID, ViInt32 arraySize, ViChar[] attributeValue);
Purpose
Queries the value of a ViString attribute.
You can use this function to get the values of instrument-specific attributes and inherent IVI 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 ViChar array to serve as a buffer for the value. You pass the number of bytes in the buffer as the arraySize parameter. If the current value of the attribute, including the terminating NUL byte, is larger than the size you indicate in the arraySize parameter, the function copies arraySize – 1 bytes into the buffer, places an ASCII NUL byte at the end of the buffer, and returns the array size you must pass to get the entire value. For example, if the value is "123456" and arraySize is 4, the function places "123" into the buffer and returns 7.
If you want to call this function just to get the required array size, you can pass 0 for arraySize and VI_NULL for the attributeValue 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 arraySize parameter.
Parameters
| Input | ||
| Name | Type | Description |
| vi | ViSession | Identifies your instrument session. vi is obtained from the niFgen_init or the niFgen_InitWithOptions functions and identifies a particular instrument session. |
| channelName | ViConstString | Specifies the name of the channel on which to check the attribute value if the attribute is channel-based. If the attribute is not channel-based, then pass VI_NULL or an empty string ("").
Default Value: "" (empty string) |
| attributeID | ViAttr | Specifies the ID of an attribute. |
| arraySize | ViInt32 | Specifies the number of bytes in the ViChar array you specify for the attributeValue parameter.
If the current value of the attribute, including the terminating NUL byte, contains more bytes than you indicate in this parameter, the function copies arraySize – 1 bytes into the buffer, places an ASCII NUL byte at the end of the buffer, and returns the array size you must pass to get the entire value. For example, if the value is "123456" and arraySize 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 attributeValue buffer parameter. |
| Output | ||
| Name | Type | Description |
| attributeValue | ViChar[] | The buffer in which the function returns the current value of the attribute. The buffer must be a ViChar data type and have at least as many bytes as indicated in the arraySize parameter.
If the current value of the attribute, including the terminating NUL byte, contains more bytes than you indicate in this parameter, the function copies arraySize – 1 bytes into the buffer, places an ASCII NUL byte at the end of the buffer, and returns the array size you must pass to get the entire value. For example, if the value is "123456" and arraySize is 4, the function places "123" into the buffer and returns 7. If you specify 0 for the arraySize parameter, you can pass VI_NULL for this parameter. |
Return Value
| Name | Type | Description | ||||||||
| Status | ViStatus | Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You can examine the status code from each call to an NI-FGEN function to determine if an error occurred.
To obtain a text description of the status code, call niFgen_error_message. To obtain additional information about the error condition, call niFgen_GetError. To clear the error information from NI-FGEN, call niFgen_ClearError. The general meaning of the status code is as follows:
|