niRFSA_LockSession

ViStatus = niRFSA_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 niRFSA_LockSession function.
• A call to NI-RFSA locked the session.

After the call to this function returns successfully, no other threads can access the instrument session until you call the niRFSA_UnlockSession function. Use niRFSA_LockSession and niRFSA_UnlockSession around a sequence of calls to NI-RFSA functions if you require that the NI-RFSA device retain its settings through the end of the sequence.

You can safely make nested calls to the niRFSA_LockSession function within the same thread. To completely unlock the session, balance each call to niRFSA_LockSession with a call to niRFSA_UnlockSession. If, however, you use the callerHasLock parameter in all calls to niRFSA_LockSession and niRFSA_UnlockSession within a function, the IVI Library locks the session only once within the function regardless of the number of calls you make to niRFSA_LockSession. Locking the session only once allows you to call niRFSA_UnlockSession just once at the end of the function.

Parameters

Input
Name	Type	Description
vi	ViSession	Identifies your instrument session. vi is obtained from the niRFSA_init or the niRFSA_initWithOptions functions and identifies a particular instrument session.
Output
Name	Type	Description
callerHasLock	ViBoolean*	This parameter serves as a convenience. If you do not want to use this parameter, pass VI_NULL. Use this parameter in complex functions to keep 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 this function or niRFSA_UnlockSession in the same function. niRFSA_LockSession and niRFSA_UnlockSession each inspect the current value and take the following actions: If the value is VI_TRUE, niRFSA_LockSession does not lock the session again. If the value is VI_FALSE, niRFSA_LockSession obtains the lock and sets the value of the parameter to VI_TRUE. If the value is VI_FALSE, niRFSA_UnlockSession does not attempt to unlock the session. If the value is VI_TRUE, niRFSA_UnlockSession releases the lock and sets the value of the parameter to VI_FALSE. Thus, you can call niRFSA_UnlockSession at the end of your function regardless of whether you actually have the lock.

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 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 niRFSA_error_message function. To obtain additional information about the error condition, call the niRFSA_GetError function. To clear the error information from the driver, call the niRFSA_ClearError function. The general meaning of the status code is as follows: Value	Meaning
0	Success
Positive Values	Warnings
Negative Values	Errors