FP_Advise

Purpose

This function continuously reads time-stamped data at a specified rate from the I/O point into a buffer. Advise is an asynchronous operation. After FP_Advise initiates the operation, it immediately returns, and the client thread continues execution. The callback function executes according to the behavior you specify with callbackMethod. The advise operation will continue to monitor the I/O point at the rate you specify until you explicitly terminate it with a call to FP_Stop or FP_Close.

Use FP_ChangeAdviseState to suspend or resume user callbacks.

Use FP_ReadCache to read the last known value on the I/O point.

Use FP_Stop to terminate a single advise operation.

Note  The recommended method of monitoring an I/O point is to schedule an advise on an I/O point, pass NULL for the function pointer, and use a timer on the UIR to periodically read the cache on the I/O point. When you use NULL for the callbackFunction pointer, your program ignores callbackMethod.

Parameter List

Caution  Do not use local data buffers, or the same data buffer for multiple advise operations, because it causes unpredictable results. It is a good idea to use distinct global data buffers for each advise task.

Parameter Discussion

PostDeferred Callbacks

This option is valid with LabWindows/CVI versions 5.0 and later. The server executes the callback in the main LabWindows/CVI thread each time LabWindows/CVI processes system events. A considerable delay could occur between the call to the function by the server and when LabWindows/CVI executes the function. Thus, for a large number of I/O points or fast advise rates, the PostDeferred queue may become full, causing the callbacks to be dropped. Call FP_FreePDCallbackBuffer in the callback function for post deferred callbacks to free the buffer allocated by the server manager.

Asynchronous Callbacks

The asynchronous call returns the data to the callback as soon as the server completes the operation. If you are using a version of LabWindows/CVI earlier than 5.5, observe the following guidelines for the callback function:

• The function must be short and must not call other I/O or UIR functions.
• Use only multithread-safe LabWindows/CVI libraries. For example, do not update UIR controls in an asynchronous callback.

Note  The recommended method of monitoring an I/O point is to schedule an advise on an I/O point, pass NULL for the function pointer, and use a timer on the UIR to periodically read the cache on the I/O point. When you use NULL for the callbackFunction pointer, your program ignores callbackMethod.

callbackFunction

If you pass a callback function into this parameter and set the callback method to post deferred, LabWindows/CVI allocates memory for every callback. You must free this memory in the callback function using the FP_FreePDCallbackBuffer function. No memory is allocated for asynchronous callbacks, so you should not use the FP_FreePDCallbackBuffer function for asynchronous callbacks.

The function has the following definition:

void CVICALLBACK yourFunction (void* buffer);

The type of the function pointer is FP_CallbackFuncPtr:

FP_CallbackFuncPtr yourfuncPtr = yourFunction;

Enter 'yourfuncPtr' in the callbackFunction control.

LabWindows/CVI returns the callback data as a pointer to void. To get back meaningful data you must cast the void pointer to a struct of the following type:

FP_CallbackParamType;

The members of the struct are

IAHandle hIOpoint; //handle to the IOPoint

IAStatus status; //status

IABoolean CBMethod;//the mechanism for the callback

IAByte* buffer; //buffer containing the data

UInt32 buffersize; //size of databuffer

IATimeStamp timeStamp; //time stamp

DWORD cParam; //user specified parameter

For example:

FP_CallbackParamType g_param;

Use g_param to read back the data in your callback function:

void yourFunction (void* buffer)

{

g_param = *((FP_CallbackParamType*) buffer); //cast data

int bsize = g_param.buffersize;

//bsize contains the buffer size

}

Return Value

The LabWindows/CVI manager or the server can return the following status codes. FP_ErrorMsg converts the status codes into descriptive strings.

Refer to the error section in your server help file for more information.