GetNextCoercionString

IVI Library

Ivi_GetNextCoercionString

Usage

ViStatus Ivi_GetNextCoercionString(ViSession vi, ViInt32 bufferSize, ViChar coercionString[ ]);

Purpose

This function obtains information regarding the oldest instance in which the IVI engine coerced an attribute value you specified to another value. This information is in a string format. It then deletes that information.

If you enable the IVI_ATTR_RECORD_COERCIONS attribute for the session, the IVI engine keeps a list of all coercions it makes on values you pass to an Ivi_SetAttribute function for a ViInt32 or ViReal64 attribute. You can use this function to retrieve information from that list. Each time you call this function, it extracts and deletes the oldest coercion record for the session.

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

The function returns the string containing the coercion information. You must provide a ViChar array to serve as a buffer for the string. You pass the number of bytes in the buffer as the Buffer Size parameter. If the current size of the coercion string, 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 you want the function to fill in the buffer regardless of the number of bytes in the string, pass a negative number for the Buffer Size parameter. If you want to call this function just to get the required buffer size, you can pass 0 for the Buffer Size and VI_NULL for the Coercion String buffer.

Remember that the checkErr and viCheckErr macros ignore positive return values. If you use one of these macros around a call to this function, you lose the required buffer size when the function returns it. To retain this information, declare a separate local variable to store the required buffer size, and use the macro around the assignment of the return value to the local variable. The following is an example:

ViStatus error = VI_SUCCESS;ViInt32 requiredBufferSize;

checkErr( requiredBufferSize =
Ivi_GetNextCoercionString(vi, 0, VI_NULL));

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 Coercion String parameter. If the current coercion string, including the terminating NUL byte, contains more bytes than 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 coercion string to the buffer regardless of the number of bytes in the string. If you pass 0, you can pass VI_NULL for the Coercion String buffer parameter.
coercionString	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 than 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 coercion records 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 Coercion String parameter.

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

If you pass 0, you can pass VI_NULL for the Coercion String buffer parameter.

coercionString

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 than 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 coercion records 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 coercion string, 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.