GetNextInterchangeCheckString

IVI Library

Ivi_GetNextInterchangeCheckString

Usage

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

Purpose

This function returns the interchangeability warnings associated with the IVI session. Interchangeability warnings indicate that using your application with a different instrument might cause different behavior.

The specific driver performs interchangeability checking if the IVI_ATTR_INTERCHANGE_CHECK attribute is set to VI_TRUE. Each time you call this function, it extracts and deletes the oldest interchangeability warning information for the session.

If the next interchangeability warning string, including the terminating NUL byte, contains more bytes than you indicate in bufSize parameter, the function copies bufSize - 1 bytes into the interchangeWarning buffer, places an ASCII NUL byte at the end of the interchangeWarning 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 interchange warning buffer and returns 7.

If you want the function to fill in the buffer regardless of the number of bytes in the string, pass a negative number for the bufSize parameter. If you want to call this function just to get the required buffer size, you can pass 0 for the bufSize and VI_NULL for the interchangeWarning buffer.

The function returns an empty string in the interchange warning parameter if no interchangeability warnings remain for the session.

Parameters

Name	Type	Description
vi	ViSession	The ViSession handle that you obtain from Ivi_SpecificDriverNew. The handle identifies a particular IVI session.
bufferSize	ViInt32	Pass the number of bytes in the ViChar array you specify for the interchange warning parameter. If the current interchange warning, including the terminating NUL byte, contains more bytes that 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 string. 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 interchange warning to the buffer regardless of the number of bytes in the string. If you pass 0, you can pass VI_NULL for the Interchange Warning buffer parameter.
interchangeWarning	ViChar[ ]	The buffer in which the function returns the description of the oldest value coercion of the instrument session. The buffer must be of type ViChar and have at least as many bytes as indicated in the Buffer Size parameter. If the current coercion string, including the terminating NUL byte, contains more bytes that 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 string. For example, if the string is "123456" and the Buffer Size is 4, the function places "123" into the buffer and returns 7. If you specify 0 for the Buffer Size parameter, you can pass VI_NULL for this parameter. When no interchange warnings remain for the session, the function returns an empty string ("") in the Coercion String parameter.

Name

Type

Description

ViSession

The ViSession handle that you obtain from Ivi_SpecificDriverNew. The handle identifies a particular IVI session.

bufferSize

ViInt32

Pass the number of bytes in the ViChar array you specify for the interchange warning parameter.

If the current interchange warning, including the terminating NUL byte, contains more bytes that 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 string. 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 interchange warning to the buffer regardless of the number of bytes in the string.

If you pass 0, you can pass VI_NULL for the Interchange Warning buffer parameter.

interchangeWarning

ViChar[ ]

The buffer in which the function returns the description of the oldest value coercion of the instrument session. The buffer must be of type ViChar and have at least as many bytes as indicated in the Buffer Size parameter.

If the current coercion string, including the terminating NUL byte, contains more bytes that 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 string. For example, if the string is "123456" and the Buffer Size is 4, the function places "123" into the buffer and returns 7.

If you specify 0 for the Buffer Size parameter, you can pass VI_NULL for this parameter.

When no interchange warnings remain for the session, the function returns an empty string ("") in the Coercion String parameter.

Return Value

Contains the status code that the function call returns.

If the function succeeds and the buffer you pass is large enough to hold the entire value, the function returns 0.

If the current length of the interchange warning, including the terminating NUL 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 NUL byte at the end of the buffer, and returns the buffer size you must pass to get the entire string. For example, if the value is "123456" and the Buffer Size is 4, the function places "123" into the buffer and returns 7.

If the function fails for some other reason, it returns a negative error code. For more information on error codes, refer to the Status return value control in one of the other function panels.