viLock

Purpose

Establishes an access mode to the specified resources.

C Syntax

ViStatus viLock(ViSession vi, ViAccessMode lockType, ViUInt32 timeout, ViKeyId requestedKey, ViChar accesskey[])

Visual Basic Syntax

viLock&(ByVal vi&, ByVal lockType&, ByVal timeout&, ByVal requestedKey$, ByVal accesskey$)

Resource Classes

All I/O session types

Parameters

Name	Direction	Description
vi	IN	Unique logical identifier to a session.
lockType	IN	Specifies the type of lock requested, either VI_EXCLUSIVE_LOCK (1) or VI_SHARED_LOCK (2).
timeout	IN	Absolute time period (in milliseconds) that a resource waits to get unlocked by the locking session before returning an error.
requestedKey	IN	This parameter is not used and should be set to VI_NULL when lockType is VI_EXCLUSIVE_LOCK. Refer to the Description section for more details about using VI_SHARED_LOCK.
accessKey	OUT	This parameter should be set to VI_NULL when lockType is VI_EXCLUSIVE_LOCK. When lockType is VI_SHARED_LOCK, the resource returns a unique access key for the lock if the operation succeeds. This accessKey can then be passed to other sessions to share the lock.

Return Values

Completion Codes	Description
VI_SUCCESS	Specified access mode was acquired.
VI_SUCCESS_NESTED_EXCLUSIVE	Specified access mode is successfully acquired, and this session has nested exclusive locks.
VI_SUCCESS_NESTED_SHARED	Specified access mode is successfully acquired, and this session has nested shared locks.

 

Error Codes	Description
VI_ERROR_INV_OBJECT	The given session reference is invalid.
VI_ERROR_RSRC_LOCKED	Specified lockType cannot be obtained because the resource is already locked with a lock type incompatible with the lock requested.
VI_ERROR_INV_LOCK_TYPE	Specified lockType is not supported by this resource.
VI_ERROR_INV_ACCESS_KEY	The requestedKey value passed in is not a valid accessKey to the specified resource.
VI_ERROR_TMO	Specified lockType could not be obtained within the specified timeout period.

Description

This operation is used to obtain a lock on the specified resource. The caller can specify the type of lock requested—exclusive or shared lock—and the length of time the operation will suspend while waiting to acquire the lock before timing out. This operation can also be used for sharing and nesting locks.

The requestedKey and the accessKey parameters apply only to shared locks. These parameters are not applicable when using the lock type VI_EXCLUSIVE_LOCK; in this case, requestedKey and accessKey should be set to VI_NULL. VISA allows user applications to specify a key to be used for lock sharing, through the use of the requestedKey parameter. Alternatively, a user application can pass VI_NULL for the requestedKey parameter when obtaining a shared lock, in which case VISA will generate a unique access key and return it through the accessKey parameter. If a user application does specify a requestedKey value, VISA will try to use this value for the accessKey. As long as the resource is not locked, VISA will use the requestedKey as the access key and grant the lock. When the operation succeeds, the requestedKey will be copied into the user buffer referred to by the accessKey parameter.

Note  If requesting a VI_SHARED_LOCK, the size of the accessKey parameter should be at least 256 bytes.

The session that gained a shared lock can pass the accessKey to other sessions for the purpose of sharing the lock. The session wanting to join the group of sessions sharing the lock can use the key as an input value to the requestedKey parameter. VISA will add the session to the list of sessions sharing the lock, as long as the requestedKey value matches the accessKey value for the particular resource. The session obtaining a shared lock in this manner will then have the same access privileges as the original session that obtained the lock.

It is also possible to obtain nested locks through this operation. To acquire nested locks, invoke the viLock() operation with the same lock type as the previous invocation of this operation. For each session, viLock() and viUnlock() share a lock count, which is initialized to 0. Each invocation of viLock() for the same session (and for the same lockType) increases the lock count. In the case of a shared lock, it returns with the same accessKey every time. When a session locks the resource a multiple number of times, it is necessary to invoke the viUnlock() operation an equal number of times in order to unlock the resource. That is, the lock count increments for each invocation of viLock(), and decrements for each invocation of viUnlock(). A resource is actually unlocked only when the lock count is 0.

The VISA locking mechanism enforces arbitration of accesses to resources on an individual basis. If a session locks a resource, operations invoked by other sessions to the same resource are serviced or returned with a locking error, depending on the operation and the type of lock used. If a session has an exclusive lock, other sessions cannot modify global attributes or invoke operations, but can still get attributes and set local attributes. If the session has a shared lock, other sessions that have shared locks can also modify global attributes and invoke operations. Regardless of which type of lock a session has, if the session is closed without first being unlocked, VISA automatically performs a viUnlock() on that session.

The locking mechanism works for all processes and resources existing on the same computer. When using remote resources, however, the networking protocol may not provide the ability to pass lock requests to the remote device or resource. In this case, locks will behave as expected from multiple sessions on the same computer, but not necessarily on the remote device. For example, when using the VXI-11 protocol, exclusive lock requests can be sent to a device, but shared locks can only be handled locally.

Related Topics

VISA Resource Template

viUnlock