niSwitch_LockSession

Specific Function

C Function Prototype

ViStatus niSwitch_LockSession (ViSession vi, ViBoolean* callerHasLock);

Purpose

This function obtains a multithread lock on the instrument session. Before it does so, it 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 niSwitch_LockSession.
• A call to the instrument driver locked the session.
• A call to the IVI engine locked the session.

After your call to niSwitch_LockSession returns successfully, no other threads can access the instrument session until you call niSwitch_UnlockSession. Use niSwitch_LockSession and niSwitch_UnlockSession around a sequence of calls to NI-SWITCH functions if you require that the instrument retain its settings through the end of the sequence. You can safely make nested calls to niSwitch_LockSession within the same thread. To completely unlock the session, balance each call to niSwitch_LockSession with a call to niSwitch_UnlockSession. If, however, you use the callerHasLock parameter in all calls to niSwitch_LockSession and niSwitch_UnlockSession within a function, the IVI Library locks the session only once within the function regardless of the number of calls you make to niSwitch_LockSession. This allows you to call niSwitch_UnlockSession just once at the end of the function.

Parameters

Name	Type	Description
vi	ViSession	A particular NI-SWITCH session established with niSwitch_InitWithTopology, niSwitch_InitWithOptions, or niSwitch_init and used for all subsequent NI-SWITCH calls.
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 niSwitch_LockSession or niSwitch_UnlockSession in the same function. The parameter is an input/output parameter. niSwitch_LockSession and niSwitch_UnlockSession each inspect the current value and take the following actions: If the value is VI_TRUE, niSwitch_LockSession does not lock the session again. If the value is VI_FALSE, niSwitch_LockSession obtains the lock and sets the value of the parameter to VI_TRUE. If the value is VI_FALSE, niSwitch_UnlockSession does not attempt to unlock the session. If the value is VI_TRUE, niSwitch_UnlockSession releases the lock and sets the value of the parameter to VI_FALSE. Thus, you can, call niSwitch_UnlockSession 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; ViBoolean haveLock = VI_FALSE; if (flags & BIT_1) { viCheckErr( niSwitch_LockSession(vi, &haveLock)); viCheckErr( TakeAction1(vi)); if (flags & BIT_2) { viCheckErr( niSwitch_UnlockSession(vi, &haveLock)); viCheckErr( TakeAction2(vi)); viCheckErr( niSwitch_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. */ niSwitch_UnlockSession(vi, &haveLock); return error; }