niDMM_LockSession

NI-DMM C/CVI/VB

previous page next page

niDMM_LockSession

ViStatus = niDMM_LockSession(ViSession Instrument_Handle, ViBoolean *Caller_Has_Lock)

Purpose

This function obtains a multithread lock on the instrument session. Before it does so, it 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:

  • The user application called this function.
  • A call to the instrument driver locked the session.
  • A call to the IVI Library locked the session.

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

Use this function and niDMM_UnlockSession around a sequence of calls to instrument driver functions if you require that the instrument retain its settings through the end of the sequence. You can safely make nested calls to this function within the same thread.

To completely unlock the session, you must balance each call to this function with a call to niDMM_UnlockSession. If, however, you use the Caller_Has_Lock parameter in all calls to this function and niDMM_UnlockSession within a function, the IVI Library locks the session only once within the function regardless of the number of calls you make to this function. This feature allows you to call niDMM_UnlockSession just once at the end of the function.

Parameters

Input
Name Type Description
Instrument_Handle ViSession Identifies a particular instrument session. You obtain the Instrument_Handle parameter from niDMM_init or niDMM_InitWithOptions. The default is None.
Output
Name Type Description
Caller_Has_Lock 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. To use this parameter, complete the following steps:
  1. Pass the address of a local ViBoolean variable.
  2. In the declaration of the local variable, initialize it to VI_FALSE (0).
  3. Pass the address of the same local variable to any other calls you make to this function or niDMM_UnlockSession in the same function.

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

If the value is VI_TRUE (1), this function does not lock the session again. If the value is VI_FALSE, this function obtains the lock and sets the value of the parameter to VI_TRUE.

If the value is VI_FALSE, niDMM_UnlockSession does not attempt to unlock the session. If the value is VI_TRUE, niDMM_UnlockSession releases the lock and sets the value of the parameter to VI_FALSE. Thus, you can, call niDMM_UnlockSession 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( NIDMM_LockSession(vi, &haveLock));
viCheckErr( TakeAction1(vi));
if (flags & BIT_2)

{

viCheckErr( NIDMM_UnlockSession(vi, &haveLock));

viCheckErr( TakeAction2(vi));

viCheckErr( NIDMM_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.

*/

niDMM_UnlockSession(vi, &haveLock);

return error;

}

Return Value

Name Type Description
Status ViStatus Reports the Status of this operation. To obtain a text description of the status code, call niDMM_error_message. To obtain additional information concerning the error condition, use niDMM_GetError.
previous page start next page