niFgen_LockSession
ViStatus niFgen_LockSession (ViSession vi, ViBoolean* callerHasLock);
Purpose
Obtains a multithread lock on the instrument session. Before it does so, this function waits until all other execution threads have released their locks on the instrument session.
Other threads might have obtained a lock on this session in the following ways:
- Your application called the niFgen_LockSession function.
- A call to the NI-FGEN locked the session.
- A call to the IVI Engine locked the session.
After your call to the niFgen_LockSession function returns successfully, no other threads can access the instrument session until you call the niFgen_UnlockSession function.
Use the niFgen_LockSession function and the niFgen_UnlockSession function around a sequence of calls to NI-FGEN functions if you require that the instrument retain its settings through the end of the sequence.
You can safely make nested calls to the niFgen_LockSession function within the same thread. To completely unlock the session, you must balance each call to the niFgen_LockSession function with a call to the niFgen_UnlockSession function. If, however, you use the callerHasLock parameter in all calls to the niFgen_LockSession function and the niFgen_UnlockSession function within a function, the IVI Engine locks the session only once within the function regardless of the number of calls you make to the niFgen_LockSession function. This configuration allows you to call the niFgen_UnlockSession function just once at the end of the function.
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. |
| Output | ||
| Name | Type | Description |
| callerHasLock | ViBoolean* | Keeps track of whether you obtained a lock and therefore need to unlock the session. Pass the address of a local ViBoolean variable. In the declaration of the local variable, initialize it to VI_FALSE. Pass the address of the same local variable to any other calls you make to the niFgen_LockSession function or the niFgen_UnlockSession function in the same function.
This parameter serves as a convenience. If you do not want to use this parameter, pass VI_NULL. This parameter is an input/output parameter. The niFgen_LockSession function and the niFgen_UnlockSession function each inspect the current value and take the following actions:
Thus, you can call the niFgen_UnlockSession function at the end of your function without worrying about whether you actually have the lock. Example: ViStatus TestFunc (ViSession vi, ViInt32 flags){
ViStatus error = VI_SUCCESS;
viCheckErr( niFgen_LockSession(vi, &haveLock));
viCheckErr( niFgen_UnlockSession(vi, &haveLock));
}
viCheckErr( TakeAction3(vi));
} Error:
/* |
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 the niFgen_error_message function. To obtain additional information about the error condition, call the niFgen_GetError function. To clear the error information from NI-FGEN, call the niFgen_ClearError function. The general meaning of the status code is as follows:
|