niRFSG_UnlockSession

NI-RFSG C Function

niRFSG_UnlockSession

C Function Prototype

ViStatus niRFSG_UnlockSession (ViSession vi, ViBoolean* callerHasLock);

Purpose

Releases a lock obtained on an NI-RFSG device session by calling the niRFSG_LockSession function.

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. The ViSession handle is obtained from the niRFSG_init function or the niRFSG_InitWithOptions function and identifies a particular instrument session.

Default Value: None

Output
Name Type Description
callerHasLock ViBoolean* Keeps 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 niRFSG_LockSession function or the niRFSG_UnlockSession function in the same function.



This parameter serves as a convenience. If you do not want to use this parameter, pass VI_NULL.

The parameter is an input/output parameter. The niRFSG_LockSession function and the niRFSG_UnlockSession each inspect the current value and take the following actions:
  • If the value is VI_TRUE, the niRFSG_LockSession function does not lock the session again. If the value is VI_FALSE, the niRFSG_LockSession function obtains the lock and sets the value of the parameter to VI_TRUE.
  • If the value is VI_FALSE, the niRFSG_UnlockSession function does not attempt to unlock the session. If the value is VI_TRUE, the niRFSG_UnlockSession function releases the lock and sets the value of the parameter to VI_FALSE.
Thus, you can call the niRFSG_UnlockSession function at the end of your function without worrying about whether you have the lock.

Example:

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

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


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. 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 niRFSG_error_message function. To obtain additional information about the error condition, call the niRFSG_GetError function. To clear the error information from the driver, call the niRFSG_ClearError function.

The general meaning of the status code is as follows:

ValueMeaning
0Success
Positive ValuesWarnings
Negative ValuesErrors