niFgen_GetNextCoercionRecord
ViStatus niFgen_GetNextCoercionRecord (ViSession vi, ViInt32 bufferSize, ViChar[] coercionRecord);
Purpose
Returns the coercion information associated with the IVI session. This function retrieves and clears the oldest instance in which the NI-FGEN coerced a value you specified to another value.
If you set the NIFGEN_ATTR_RECORD_COERCIONS attribute to VI_TRUE, NI-FGEN keeps a list of all coercions it makes on ViInt32 or ViReal64 values that you pass to NI-FGEN functions. You use this function to retrieve information from that list.
If the next coercion record 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 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 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 coercionRecord buffer parameter.
The function returns an empty string in the coercionRecord parameter if no coercion records remain for the session.
Parameters
| Input | ||
| Name | Type | Description |
| vi | ViSession | Identifies your instrument session. vi is obtained from the niFgen_init or the niFgen_InitWithOptions functions and identifies a particular instrument session. |
| bufferSize | ViInt32 | Specifies the number of bytes in the ViChar array you specify for the coercionRecord parameter.
If the next coercion record 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 NUL byte at the end of the buffer, and returns the buffer size that 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 coercionRecord buffer parameter. Default Value: None |
| Output | ||
| Name | Type | Description |
| coercionRecord | ViChar[] | Returns the next coercion record for the IVI session. If there are no coercion records, 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 coercion record 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 NUL byte at the end of the buffer, and returns the buffer size that 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 coercion records remain for the session. |
Return Value
| Name | Type | Description | ||||||||
| Status | ViStatus | Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. You can examine the status code from each call to an NI-FGEN function to determine if an error occurred.
To obtain a text description of the status code, call niFgen_error_message. To obtain additional information about the error condition, call niFgen_GetError. To clear the error information from NI-FGEN, call niFgen_ClearError. The general meaning of the status code is as follows:
|