niFgen_LockSession

NI-FGEN C Function

niFgen_LockSession

ViStatus niFgen_LockSession (ViSession vi, ViBoolean* callerHasLock);

Purpose

Obtains a multithread lock on the instrument session. Before it does so, this function 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 the niFgen_LockSession function.
  • A call to the NI-FGEN locked the session.
  • A call to the IVI Engine locked the session.

After your call to the niFgen_LockSession function returns successfully, no other threads can access the instrument session until you call the niFgen_UnlockSession function.

Use the niFgen_LockSession function and the niFgen_UnlockSession function around a sequence of calls to NI-FGEN functions if you require that the instrument retain its settings through the end of the sequence.

You can safely make nested calls to the niFgen_LockSession function within the same thread. To completely unlock the session, you must balance each call to the niFgen_LockSession function with a call to the niFgen_UnlockSession function. If, however, you use the callerHasLock parameter in all calls to the niFgen_LockSession function and the niFgen_UnlockSession function within a function, the IVI Engine locks the session only once within the function regardless of the number of calls you make to the niFgen_LockSession function. This configuration allows you to call the niFgen_UnlockSession function just once at the end of the function.

Parameters

Input
Name Type Description
vi ViSession Identifies your instrument session. vi is obtained from the niFgen_init or the niFgen_InitWithOptions functions and identifies a particular instrument session.
Output
Name Type Description
callerHasLock ViBoolean* Keeps track of whether you obtained 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 niFgen_LockSession function or the niFgen_UnlockSession function in the same function.

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

This parameter is an input/output parameter. The niFgen_LockSession function and the niFgen_UnlockSession function each inspect the current value and take the following actions:

  • If the value is VI_TRUE, the niFgen_LockSession function does not lock the session again. If the value is VI_FALSE, the niFgen_LockSession function obtains the lock and sets the value of the parameter to VI_TRUE.
  • If the value is VI_FALSE, the niFgen_UnlockSession function does not attempt to unlock the session. If the value is VI_TRUE, the niFgen_UnlockSession function releases the lock and sets the value of the parameter to VI_FALSE.

Thus, you can call the niFgen_UnlockSession function 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( niFgen_LockSession(vi, &haveLock));
viCheckErr( TakeAction1(vi));
if (flags & BIT_2)
{

viCheckErr( niFgen_UnlockSession(vi, &haveLock));
viCheckErr( TakeAction2(vi));
viCheckErr( niFgen_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.
*/
niFgen_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. You can examine the status code from each call to an NI-FGEN function to determine if an error occurred. To obtain a text description of the status code, call the niFgen_error_message function. To obtain additional information about the error condition, call the niFgen_GetError function. To clear the error information from NI-FGEN, call the niFgen_ClearError function.

The general meaning of the status code is as follows:

Value Meaning
0 Success
Positive Values Warnings
Negative Values Errors