niSwitch_GetNextInterchangeWarning

NI-SWITCH Functions

niSwitch_GetNextInterchangeWarning

Specific Function

C Function Prototype

ViStatus niSwitch_GetNextInterchangeWarning (ViSession vi, ViInt32 bufferSize, ViChar[] interchangeWarning);

Purpose

This function returns the interchangeability warnings associated with the IVI session. It retrieves and clears the oldest instance in which the class driver recorded an interchangeability warning. Interchangeability warnings indicate that using your application with a different instrument might cause different behavior. You use this function to retrieve interchangeability warnings. The driver performs interchangeability checking when the NISWITCH_ATTR_INTERCHANGE_CHECK attribute is set to VI_TRUE. The function returns an empty string in the interchangeWarning parameter if no interchangeability warnings remain for the session. In general, the instrument driver generates interchangeability warnings when an attribute that affects the behavior of the instrument is in a state that you did not specify.

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.

bufferSize ViInt32 Pass the number of bytes in the ViChar array you specify for the interchangeWarning parameter.
If the next interchangeability warning string, including the terminating NUL byte, contains more bytes than you indicate in this parameter, the function copies bufferSize–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 bufferSize 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 Interchange Warning buffer parameter.

interchangeWarning ViChar[] Returns the next interchange warning for the IVI session. If there are no interchange warnings, the function returns an empty string. The buffer must contain at least as many elements as the value you specify with the bufferSize parameter.
If the next interchangeability warning string, including the terminating NUL byte, contains more bytes than you indicate with the bufferSize parameter, the function copies bufferSize–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 bufferSize is 4, the function places "123" into the buffer and returns 7. This parameter returns an empty string if no interchangeability warnings remain for the session.