niDCPower_UnlockSession

NI-DCPower Function Reference

previous page next page

niDCPower_UnlockSession

ViStatus niDCPower_UnlockSession(ViSession vi, ViBoolean *callerHasLock)

Purpose

Releases a lock that you acquired on an device session using niDCPower_LockSession. Refer to niDCPower_LockSession for additional information on session locks.

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 attribute is optional. If you do not want to use this attribute, pass VI_NULL.

Use this attribute 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 niDCPower_LockSession or niDCPower_UnlockSessionin the same function.

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

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_UnlockSession(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_UnlockSession(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