ClassPrefix_GetNextInterchangeWarning
IVI Inherent Function
To form the ClassPrefix_ of the function name, use the prefix of the class driver with which you are working. For example, if you are working with the IviDmm class driver, use the prefix IviDmm_ to create the correct function name, IviDmm_GetNextInterchangeWarning.
C Function Prototype
ViStatus ClassPrefix_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. Alternately, you can use NI Spy to view interchangeability warnings.
If you pass a negative number for the buffer size, the function copies the value to the buffer regardless of the number of bytes in the value.
If you pass 0 for the buffer size, the function returns the string length for the next interchange warning in the queue. When you pass 0 for the buffer size, you can pass VI_NULL for the Interchange Warning buffer parameter.
The function returns an empty string in the interchangeWarning parameter if no interchangeability warnings remain for the session.
Interchangeability checking examines the attributes in a capability group only if you specify a value for at least one attribute within that group. In general, the class driver generates interchangeability warnings when it encounters one of the following conditions:
- An attribute that affects the behavior of the instrument is in a state that you did not specify.
- You set a class-defined attribute to an instrument specific value.
- You set the value of an attribute that the class driver defines as read-only.
- The class driver encounters an error when it tries to apply a value to an extension attribute that your program never configures.
Parameters
| Name | Type | Description |
|---|---|---|
| vi | ViSession | The instrument handle that you obtain from the ClassPrefix_init or ClassPrefix_InitWithOptions functions. The handle identifies a particular IVI session. |
| bufferSize | ViInt32 | Pass the number of bytes in the ViChar array you specify for the coercionRecord parameter. 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 a 0, you can pass VI_NULL for the interchangeWarning parameter in order to get the buffer size for the next coercion string, including the NULL byte. You can use this value to allocate the buffer, and pass it as the actual buffer size in a subsequent call to this function to retrieve the complete interchange warning string. If the next coercion string, including the terminating NULL 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 essentially truncating the coercion string. Default Value: None |
| interchange Warning |
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 NULL 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 essentially truncating the interchangeability warning string. You may pass VI_NULL for this parameter and a 0 for the bufferSize parameter if you want to obtain the required buffer size. |
Return Values
Reports the status of the operation.
If the function succeeds and the buffer you pass is large enough to hold the entire coercion record string, the function returns 0.
If the next coercion record string, including the terminating NULL byte, is larger than the size you indicate in 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 the bufferSize 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.