FP_Advise

FieldPoint LabWindows/CVI Interface

FP_Advise

IAStatus FP_Advise (IAHandle serverHandle, IAHandle IOPointHandle, long adviseRate, IABoolean notifyOnChange, IAByte buffer[], unsigned long bufferSize, IABoolean callbackMethod, IAHandle callbackFunction, DWORD cParam, IATaskID *taskID);

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

Name Type Description
serverHandle IAHandle Handle to a specific server session. Create the handle with FP_Open.
IOPointHandle IAHandle The handle that FP_CreateTagIOPoint returns. The handle identifies the I/O point described in this function.
adviseRate long Specifies the poll rate for the I/O point in milliseconds. An advise rate of 1,000 indicates that the I/O point is polled once per second.
notifyOnChange IABoolean Indicates when to execute the callback. When TRUE, the server invokes the callback only if the value changed from the last read. If it is FALSE, the server invokes the callback after every read.

Valid Range:
(0) FALSE - Notify Always
(1) TRUE - Notify Only on Change
buffer IAByte[ ] Memory that you allocate. The server copies data into this buffer.
bufferSize unsigned long Indicates the number of bytes allocated in buffer.
callbackMethod IABoolean Specifies which type of callback mechanism the server uses for the specified Advise task. The FieldPoint LabWindows/CVI interface provides two different methods, as described below:

(0) FALSE - PostDeferred Callbacks
(1) TRUE - Asynchronous Callbacks
callbackFunction IAHandle A function pointer (as defined with the specification that follows) or a NULL value indicating no callback function. When this parameter is NULL, your program ignores callbackMethod.
cParam DWORD Parameter that you define to be passed to the callback. You can use this parameter to pass meaningful or useful data when processing the reply.
taskID IATaskID Created by FP_Advise and should be used when calling FP_ReadCache or FP_Stop.


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.

LabWindows/CVI Manager-Level Error Codes 0x8480 IA_MGR_ERROR
0x8484 IA_MGR_SERVER_NOT_LOADED
0x8487 IA_MGR_INVALID_SERVER_HND
FieldPoint Server-Level Standard Error Codes 0x8000 to 0x83FF

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