ClassPrefix_GetNextCoercionRecord
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_GetNextCoercionRecord.
C Function Prototype
ViStatus ClassPrefix_GetNextCoercionRecord (ViSession vi, ViInt32 bufferSize, ViChar coercionRecord[]);
Purpose
This function obtains the coercion information associated with the IVI session. It retrieves and clears the oldest instance in which the specific driver coerced a value you specified to another value.
If you set the CLASSPREFIX_ATTR_RECORD_COERCIONS attribute to VI_TRUE, the specific driver keeps a list of all coercions it makes on ViInt32 or ViReal64 values you pass to instrument driver functions. Use this function to retrieve information from that list. Alternatively, you can use NI Spy to view the coercion information.
If you pass a negative number for the buffer size, the function copies the value to the coercionRecord 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 coercion in the queue. When you pass 0 for the buffer size, you can pass VI_NULL for the coercionRecord buffer parameter.
The function returns an empty string in the coercionRecord parameter if no interchangeability warnings remain for the session.
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 interchangeWarning 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 |
| coercion Record | ViChar[] | Returns the next coercion for the IVI session. If there are no coercions, 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 coercion 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.