niSwitch_GetAttributeViString

Specific Function

C Function Prototype

ViStatus niSwitch_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. Pass the number of bytes in the buffer as arraySize. If the current value of the attribute, including the terminating NULL byte, is larger than the size you indicate in arraySize, the function copies arraySize-1 bytes into the buffer, places an ASCII NULL 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 arraySize.

Parameters

Name	Type	Description
vi	ViSession	A particular NI-SWITCH session established with niSwitch_InitWithTopology, niSwitch_InitWithOptions, or niSwitch_init and used for all subsequent NI-SWITCH calls.
channelName	ViConstString	Some attributes are unique for each channel. For these, pass the name of the channel. Other attributes are unique for each switch. Pass VI_NULL or an empty string for this parameter. The default value is an empty string.
attributeID	ViAttr	Pass the ID of an attribute. From the function panel window in LabWindows/CVI, you can use this control as follows. Click on the control or press <ENTER>, <spacebar>, or <ctrl-down arrow>, to display a dialog box containing a hierarchical list of the available attributes. Attributes whose value cannot be set are dim. Help text is shown for each attribute. Select an attribute by double-clicking on it or by selecting it and then pressing <ENTER>. A ring control at the top of the dialog box allows you to see all IVI attributes or only the attributes of the ViInt32 type. 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 you want to enter a variable name, press <CTRL-T> to change this ring control to a manual input box. If the attribute in this ring control has constants as valid values, you can view the constants by moving to the Attribute Value control and pressing <ENTER>.
arraySize	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 Array Size-1 bytes into the buffer, places an ASCII NULL 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 the Array 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. The default value is 512.
attributeValue	ViChar[]	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 arraySize parameter. If the current value of the attribute, including the terminating NULL byte, contains more bytes that you indicate in this parameter, the function copies arraySize-1 bytes into the buffer, places an ASCII NULL byte at the end of the buffer, and returns the array size you must pass to get the entire value.