niDCPower_LockSession

NI-DCPower Function Reference

previous page next page

niDCPower_LockSession

ViStatus niDCPower_LockSession(ViSession vi, ViBoolean *callerHasLock)

Purpose

Obtains a multithread lock on the device session. Before doing so, the software waits until all other execution threads release their locks on the device session.

Other threads may have obtained a lock on this session for the following reasons:

  • The application called the niDCPower_LockSession function.
  • A call to NI-DCPower locked the session.
  • A call to the IVI engine locked the session.
  • After a call to the niDCPower_LockSession function returns successfully, no other threads can access the device session until you call the niDCPower_UnlockSession function.
  • Use the niDCPower_LockSession function and the niDCPower_UnockSession function around a sequence of calls to instrument driver functions if you require that the device retain its settings through the end of the sequence.

You can safely make nested calls to the niDCPower_LockSession function within the same thread. To completely unlock the session, you must balance each call to the niDCPower_LockSession function with a call to the niDCPower_UnockSession function. If, however, you use Caller_Has_Lock in all calls to the niDCPower_LockSession and niDCPower_UnockSession 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 niDCPower_LockSession function. This behavior allows you to call the niDCPower_UnockSession function just once at the end of the function.

Parameters

Input
Name Type Description
vi ViSession Identifies a particular instrument session. vi is obtained from the niDCPower_init or niDCPower_InitWithOptions function.
Output
Name Type Description
callerHasLock ViBoolean* This parameter is optional. 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 the niDCPower_LockSession function or the niDCPower_UnockSession function in the same function.

The parameter is an input/output parameter. The niDCPower_LockSession and niDCPower_UnockSession functions each inspect the current value and take the following actions.
  • If the value is VI_TRUE, the niDCPower_LockSession function does not lock the session again.
  • If the value is VI_FALSE, the niDCPower_LockSession function obtains the lock and sets the value of the parameter to VI_TRUE.
  • If the value is VI_FALSE, the niDCPower_UnlockSession function does not attempt to unlock the session.
  • If the value is VI_TRUE, the niDCPower_UnlockSession function releases the lock and sets the value of the parameter to VI_FALSE.
Thus, you can, call the niDCPower_UnockSession function at the end of your function without worrying about whether you actually have the lock, as shown in the following example.

ViStatus TestFunc (ViSession vi, ViInt32 flags)
{
ViStatus error = VI_SUCCESS;
ViBoolean haveLock = VI_FALSE;

if (flags & BIT_1)
{
viCheckErr( niDCPower_LockSession(vi, &haveLock));
viCheckErr( TakeAction1(vi));
if (flags & BIT_2)
{
viCheckErr( niDCPower_UnockSession(vi, &haveLock));
viCheckErr( TakeAction2(vi));
viCheckErr( niDCPower_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.*/
niDCPower_UnockSession(vi, &haveLock);
return error;
}

Return Value

Name Type Description
StatusViStatusReports the status of this operation. To obtain a text description of the status code, call the niDCPower_error_message function. To obtain additional information concerning the error condition, call the niDCPower_GetError function.
previous page start next page