UnlockSession

IVI Library

Ivi_UnlockSession

Usage

ViStatus Ivi_UnlockSession(ViSession vi, ViBoolean* callerHasLock);

Purpose

This function releases a lock that you acquired on an instrument session using Ivi_LockSession. Refer to Ivi_LockSession for additional information on session locks.

Instrument drivers export this function to the end-user through the PREFIX_UnlockSession function.

Parameters

Name Type Description
vi ViSession

The ViSession handle that you obtain from Ivi_SpecificDriverNew. The handle identifies a particular IVI session.

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. Initialize the local variable to VI_FALSE when you declare it. Pass the same address to any other calls you make to Ivi_LockSession or Ivi_UnlockSession in the same function.

The parameter is an input/output parameter. Ivi_LockSession and Ivi_UnlockSession each inspect the current value and take the following actions:

    If the value is VI_TRUE, Ivi_LockSession does not lock the session again. If the value is VI_FALSE, Ivi_LockSession obtains the lock and sets the value of the parameter to VI_TRUE.
    If the value is VI_FALSE, Ivi_UnlockSession does not attempt to unlock the session. If the value is VI_TRUE, Ivi_UnlockSession unlocks the lock and sets the value of the parameter to VI_FALSE.

Thus, you can, call Ivi_UnlockSession at the end of your function without worrying about whether you actually have the lock.

Example:

ViStatus PREFIX_Func (ViSession vi, ViInt32 flags){

ViStatus error = VI_SUCCESS;
ViBoolean haveLock = VI_FALSE;

if (flags & BIT_1)

{
viCheckErr( Ivi_LockSession(vi, &haveLock));
viCheckErr( TakeAction1(vi));

if (flags & BIT_2)

{
viCheckErr( Ivi_UnlockSession(vi, &haveLock));
viCheckErr( TakeAction2(vi));
viCheckErr( Ivi_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.

*/
Ivi_UnlockSession(vi, &haveLock);
return error;

}

Return Value

Contains the status code that the function call returns. IVI engine functions can return error and warning values from several sets of status codes. Some status codes are unique to the IVI engine. Other status codes are the same codes that VISA Library functions return. Still others are error or warning values that functions in specific instrument drivers return. Each set of status codes has its own numeric range.

Regardless of the source of the status code, 0 always indicates success, a positive value indicates a warning, and a negative value indicates an error.

Related Topic

IVI Status Codes