niSync_GetAttributeViString

C Function Prototype

ViStatus niSync_GetAttributeViString (ViSession vi, ViConstString terminalName, ViAttr attributeID, ViInt32 bufferSize, ViChar[] attributeValue);

Purpose

Queries the value of a ViString attribute.

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 bufferSize parameter. If the current value of the attribute, including the terminating NUL byte, is larger than the size you indicate in the bufferSize 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 to call this function just to get the required buffer size, you can pass 0 for bufferSize and VI_NULL for the attributeValue parameter.

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

Name Type Description
vi ViSession The session handle that you obtain from niSync_init. The handle identifies a particular instrument session.

activeItem ViConstString Ignored for most attributes. For those attributes that are specific to a given terminal, you must specify the terminal name (for example, NISYNC_VAL_PFI0).

attributeID ViAttr Specifies the ID of the attribute you want to get.

bufferSize ViInt32 Specifies the number of bytes in the ViChar array you specify for attributeValue.

If the current value of the attribute, including the terminating NUL byte, contains more bytes than 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 attributeValue buffer parameter.

Default Value: 256

attributeValue ViChar[] Returns the current value of the attribute. This buffer must be of type ViChar and have at least as many bytes as indicated in bufferSize.

If the current value of the attribute, including the terminating NUL byte, contains more bytes than 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 bufferSize parameter, you can pass VI_NULL for this parameter.

Return Values