niRFSG_LockSession
C Function Prototype
ViStatus niRFSG_LockSession (ViSession vi, ViBoolean* callerHasLock);
Purpose
Obtains a multithread lock on the instrument session. Before doing 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 already called the niRFSG_LockSession function.
- A call to NI-RFSG locked the session.
After the call to this function returns successfully, no other threads can access the instrument session until you call the niRFSG_UnlockSession function. Use the niRFSG_LockSession function and the niRFSG_UnlockSession function around a sequence of calls to NI-RFSG functions if you require that the NI-RFSG device retain its settings through the end of the sequence.
You can safely make nested calls to the niRFSG_LockSession function within the same thread. To completely unlock the session, balance each call to the niRFSG_LockSession function with a call to the niRFSG_UnlockSession function. If, however, you use the callerHasLock parameter in all calls to the niRFSG_LockSession function and the niRFSG_UnlockSession function within a function, the IVI Library locks the session only once within the function regardless of the number of calls you make to the niRFSG_LockSession function. Locking the session only once allows you to call niRFSG_UnlockSession just once at the end of the function.
Parameters
| Input | ||
| Name | Type | Description |
| vi | ViSession | Identifies your instrument session. The ViSession handle is obtained from the niRFSG_init function or the niRFSG_InitWithOptions function and identifies a particular instrument session. Default Value: None |
| Output | ||
| Name | Type | Description |
| callerHasLock | ViBoolean* | Keeps track of whether you obtain 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 niRFSG_LockSession function or the niRFSG_UnlockSession function in the same function. This parameter serves as a convenience. If you do not want to use this parameter, pass VI_NULL. The parameter is an input/output parameter. The niRFSG_LockSession function and the niRFSG_UnlockSession each inspect the current value and take the following actions:
Example: ViStatus TestFunc (ViSession vi, ViInt32 flags) { ViStatus error = VI_SUCCESS; ViBoolean haveLock = VI_FALSE; if (flags & BIT_1) { viCheckErr( niRFSG_LockSession(vi, &haveLock)); viCheckErr( TakeAction1(vi)); if (flags & BIT_2) { viCheckErr( niRFSG_UnlockSession(vi, &haveLock)); viCheckErr( TakeAction2(vi)); viCheckErr( niRFSG_LockSession(vi, &haveLock); } if (flags & BIT_3) viCheckErr( TakeAction3(vi)); } Error: /* At this point, you cannot really be sure that you have the lock. Fortunately, the haveLock variable takes care of that for you. */ niRFSG_UnlockSession(vi, &haveLock); return 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. Examine the status code from each call to an instrument driver function to determine if an error occurred.
To obtain a text description of the status code, call the niRFSG_error_message function. To obtain additional information about the error condition, call the niRFSG_GetError function. To clear the error information from the driver, call the niRFSG_ClearError function. The general meaning of the status code is as follows:
|