IBLCK

Board-Level/Device-Level


Purpose

Acquire or release an exclusive device or interface lock for the current process.

Format

C

unsigned int iblck (int ud, int v, unsigned int LockWaitTime, void * Reserved)

Interactive Control (Usage Notes)

iblck v LockWaitTime

Input

ud Board or device descriptor
v Indicates whether to acquire or release the interface lock
LockWaitTime Time period (in milliseconds) to wait for an exclusive lock before returning ELCK
Reserved Reserved for future use; must be NULL

Output

Function Return The value of Ibsta

Description

Board-Level

If v is 1, the driver attempts to acquire an exclusive lock on the interface for the current process. The call fails with ELCK (that is, the call returns with ERR set in Ibsta and Iberr set to ELCK) if the lock could not be acquired within the timeout period specified by LockWaitTime.

If v is 0, a lock previously acquired by the current process is released. Only the process that acquired an interface lock can release a lock. If v is zero, and no lock exists for the process, the call fails with ELCK. LockWaitTime is ignored when using iblck to release interface locks.

If a process has acquired a lock, all GPIB calls by that process for that interface occur normally.

If a process has acquired a lock, all GPIB calls (except iblck and board-level ibfind) by other processes for that interface fail immediately with ELCK. iblck calls by other processes attempt to acquire a lock; the call fails with ELCK only after the timeout period has elapsed. Board-level ibfind fails with ELCK but returns a valid unit descriptor.

Interface locks are exclusive and are not shareable among processes. If a process has a lock for an interface, no other process can acquire a lock associated with that interface.

A process may acquire multiple (redundant) locks on an interface. The driver maintains a reference count of the number of outstanding locks per interface and does not unlock the interface until the reference count is 0. If the iblck call is successful, that is, if ERR is not set in Ibsta, Ibcnt contains the number of locks remaining in effect for ud, regardless of the value of v.

An interface lock is associated with a process and a GPIB interface. An acquired lock remains in effect until the lock is released. Each successful call to acquire a lock should have a corresponding call to release the lock. Calling ibonl (0 or 1) releases all interface locks held by that process for the interface described by ud.

A LockWaitTime of 0 specifies a 0 ms wait period. If the interface is locked by another process, then iblck returns immediately with ELCK. Otherwise the process acquires the lock and returns.

Device-Level

If v is 1, the driver attempts to acquire an exclusive lock on the device for the input device descriptor. The call fails with ELCK (that is, the call returns with ERR set in Ibsta and Iberr set to ELCK) if the lock could not be acquired within the timeout period specified by LockWaitTime.

If v is 0, a lock previously acquired by ud is released. Only the descriptor that acquired a device lock can release a lock. If v is zero, and no lock exists for the descriptor, the call fails with ELCK. LockWaitTime is ignored when using iblck to release device locks.

Device locks are descriptor specific. If a given descriptor is used to acquire a lock on a device, no other descriptor with the same PAD/SAD configuration can acquire a lock associated with that device.

Two rules determine whether a request to acquire a GPIB lock succeeds:

When a descriptor is used to acquire a device lock, all GPIB calls using that descriptor occur normally with the following exception: ibconfig cannot be called with ibcPAD or ibcSAD. These calls are disallowed because they can cause a change in the primary or secondary address of the locked device. If the device is locked, these calls have no effect and fail with ELCK. You must release the device lock with iblck before using any of these calls.

When a descriptor has a device lock, all device-level GPIB calls (except iblck and ibdev) by other descriptors that require the locked PAD/SAD resources are disallowed and fail with the ERR bit set in Ibsta, and Iberr set to ELCK. iblck calls by other descriptors for that device attempt to acquire a lock; the call fails with ELCK only after the timeout period has elapsed. ibdev fails with ELCK but returns a valid unit descriptor.

A descriptor may be used to acquire multiple (redundant) locks on a device. The driver maintains a reference count of the number of outstanding locks per device and does not unlock the device until the reference count is zero. If the iblck call is successful (that is, if ERR is not set in Ibsta), Ibcnt contains the number of locks remaining in effect for ud, regardless of the value of v.

A device lock is associated with a device descriptor. An acquired lock remains in effect until the lock is released. Each successful call to acquire a lock should have a corresponding call to release the lock. Calling ibonl (0 or 1) releases all device locks held for the device described by ud.

A LockWaitTime of 0 specifies a 0 ms wait period. If the board or device is locked by another process, iblck returns immediately with ELCK. Otherwise, the process acquires the lock and returns.

Possible Errors

EARG v is not 0 or 1, or Reserved is not NULL.
ECAP Unable to acquire the requested lock because the maximum lock reference count for ud has been reached.
EDVR The NI-488.2 driver is either configured incorrectly or is not properly installed.
EHDL ud is invalid or out of range.
ELCK Unable to acquire the requested lock within the timeout period because a different process owns a lock on that interface. Or, unable to release a lock because the process currently has no lock for ud.
ENEB The interface is not installed or is not properly configured.
EOIP Asynchronous I/O is in progress.